LEOContextGroup

Introduction

A context group is a crude, basic security mechanism that can insulate scripts running in different contexts from each other. Every context belongs to a group, which holds global data shared by all its contexts, which includes safe references to objects and values that may go away.



Functions

LEOContextGroupCreate
LEOContextGroupCreateNewObjectIDAndSeedForPointer
LEOContextGroupCreateNewObjectIDForPointer
LEOContextGroupGetPointerForObjectIDAndSeed
LEOContextGroupGetSeedForObjectID
LEOContextGroupHandlerIDForHandlerName
LEOContextGroupHandlerNameForHandlerID
LEOContextGroupRecycleObjectID
LEOContextGroupRelease
LEOContextGroupRetain

LEOContextGroupCreate


LEOContextGroup* LEOContextGroupCreate(
    void );  // Gives referenceCount of 1. 
Discussion

Creates a context group for use with LEOContexts. The LEOContextGroup* is reference-counted and its reference count is set to 1, so when you're done with it, you can release it. When a context is attached to a context group, the context retains its group to ensure it doesn't go away.

See Also


LEOContextGroupCreateNewObjectIDAndSeedForPointer


void LEOContextGroupCreateNewObjectIDAndSeedForPointer(
    LEOContextGroup *inContext,
    LEOObjectID *outObjectID,
    LEOObjectSeed *outSeed,
    void *theValue );  
Discussion

Create a new object ID and seed that can be used to reference the given pointer.

See Also


LEOContextGroupCreateNewObjectIDForPointer


Discussion

Create a new object ID that can be used to reference the given pointer. In general, you want to call LEOContextGroupCreateNewObjectIDAndSeedForPointer instead of this, an object ID is useless without a seed. For historical reasons, old code still calls this followed by LEOContextGroupGetSeedForObjectID

Deprecated

See Also


LEOContextGroupGetPointerForObjectIDAndSeed


Discussion

Obtain the pointer that corresponds to the given object ID and seed pair. If the given pointer has already been recycled, this will return NULL.

See Also


LEOContextGroupGetSeedForObjectID


Discussion

Before LEOContextGroupCreateNewObjectIDAndSeedForPointer existed, you used this method to get the seed for a given object ID after calling LEOContextGroupCreateNewObjectIDForPointer, because references to an object ID must store a seed to ensure they are getting the actual pointer they originally wanted to reference and not a pointer that is in there because the slot has been reused.

Deprecated

See Also


LEOContextGroupHandlerIDForHandlerName


LEOHandlerID LEOContextGroupHandlerIDForHandlerName(
    LEOContextGroup *inContext,
    const char *handlerName );  
Discussion

Convert the provided handler-name into a LEOHandlerID. All different spellings of the (case-insensitive) handler name map to the same handler ID.

See Also


LEOContextGroupHandlerNameForHandlerID


const char* LEOContextGroupHandlerNameForHandlerID(
    LEOContextGroup *inContext,
    LEOHandlerID inHandlerID );  
Discussion

Convert the provided LEOHandlerID back into a handler name. Note that, since handler names are case insensitive, you may get a different string than you originally passed to LEOContextGroupHandlerIDForHandlerName.

See Also


LEOContextGroupRecycleObjectID


Discussion

If a pointer to which references exist is going away, it needs to unregister using this call. Anyone requesting the pointer for this object ID and seed will from then on get NULL back.

See Also


LEOContextGroupRelease


void LEOContextGroupRelease(
    LEOContextGroup *inGroup );  // Subtracts 1 from referenceCount. If it hits 0, disposes of inScript. 
Discussion

Give up ownership of the given context group. You acquire ownership by either creating the context group, or by retaining it. Giving up ownership decreases its reference count by 1. When the last owner releases the object (and the reference count reaches 0), the context group is freed.

See Also


LEOContextGroupRetain


LEOContextGroup* LEOContextGroupRetain(
    LEOContextGroup *inGroup );  // Adds 1 to referenceCount. Returns inGroup. 
Return Value

Returns inGroup so you can assign it to a variable in a struct, or a global, or whatever makes sense.

Discussion

Acquire ownership of the given context group, so that when the current owner releases it the object still stays around for your use. Increases the reference count by 1.

See Also


Typedefs

LEOContextGroup

LEOContextGroup


typedef struct LEOContextGroup { 
    size_t referenceCount; // Reference count for this object, i.e. number of contexts still attached to this object. 
    LEOContextGroupFlags flags; // Flags that influence instructions running in this context. 
    struct LEOArrayEntry *globals; // Associative array containing global variables. 
    LEOHandlerCount numHandlerNames; // Number of slots in handlerNames array. 
    char **handlerNames; // Array of handler names. The indexes into this array are 'handler IDs' used throughout the bytecode. 
    size_t numReferences; // Available slots in "references" array. 
    LEOObject *references; // "Master pointer" table for references so we can detect when a reference goes away. 
    void (*messageSent)(
        LEOHandlerID sentMessage,
        struct LEOContextGroup* inContext ); 
} LEOContextGroup;  
Fields
referenceCount

Reference count for this object, i.e. number of contexts still attached to this object.

flags

Flags that influence instructions running in this context.

globals

An associative array of LEOValues of various kinds representing global variables.

numReferences

Number of items in the references array.

references

An array of "master pointers" to values to which references have been created.

Discussion

All LEOContexts belong to a Context group that contains references and other global data they share. You can insulate running scripts from each other by placing them in a different context group.

See Also