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 *inUserData,
    LEOUserDataCleanUpFuncPtr inCleanUpFunc );  // 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

LEOObjectID LEOContextGroupCreateNewObjectIDForPointer(
    LEOContextGroup *inContext,
    void *theValue );  

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

void* LEOContextGroupGetPointerForObjectIDAndSeed(
    LEOContextGroup *inContext,
    LEOObjectID inObjectID,
    LEOObjectSeed inObjectSeed );  

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

LEOObjectSeed LEOContextGroupGetSeedForObjectID(
    LEOContextGroup *inContext,
    LEOObjectID inID );  

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

void LEOContextGroupRecycleObjectID(
    LEOContextGroup *inContext,
    LEOObjectID inObjectID );  

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 ); 
    void *userData; 
    LEOUserDataCleanUpFuncPtr cleanUpUserData; 
} LEOContextGroup;  

Fields

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