All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Context manager

Path: /sdk/add_on/contextmgr/

The `CContextMgr` is a class designed to aid the management of multiple simultaneous scripts executing in parallel. It supports both concurrent script threads and co-routines.

If the application doesn't need multiple contexts, i.e. all scripts that are executed always complete before the next script is executed, then this class is not necessary.

The context manager uses asIScriptEngine::RequestContext to take advantage of any context callbacks registered with the engine, e.g. for debugging or pooling.

Multiple context managers can be used, for example when you have a group of scripts controlling in-game objects, and another group of scripts controlling GUI elements, then each of these groups may be managed by different context managers.

Observe that the context manager class hasn't been designed for multi-threading, so you need to be careful if your application needs to execute scripts from multiple threads.

See Also
  The samples Concurrent scripts and Co-routines for uses

# Public C++ interface

class CContextMgr
{
public:
CContextMgr();
~CContextMgr();
// Set the function that the manager will use to obtain the time in milliseconds.
void SetGetTimeCallback(TIMEFUNC_t func);
// Registers the following:
//
// void sleep(uint milliseconds)
//
// The application must set the get time callback for this to work
void RegisterThreadSupport(asIScriptEngine *engine);
// Registers the following:
//
// funcdef void coroutine(dictionary@)
// void createCoRoutine(coroutine @func, dictionary @args)
// void yield()
void RegisterCoRoutineSupport(asIScriptEngine *engine);
// Create a new context, prepare it with the function, then return
// it so that the application can pass the argument values. The context
// will be released by the manager after the execution has completed.
// Set keepCtxAfterExecution to true if the application needs to retrieve
// information from the context after it the script has finished.
asIScriptContext *AddContext(asIScriptEngine *engine, asIScriptContext *func, bool keepCtxAfterExecution = false);
// If the context was kept after the execution, this method must be
// called when the application is done with the context so it can be
// returned to the pool for reuse.
void DoneWithContext(asIScriptContext *ctx);
// Create a new context, prepare it with the function, then return
// it so that the application can pass the argument values. The context
// will be added as a co-routine in the same thread as the currCtx.
asIScriptContext *AddContextForCoRoutine(asIScriptContext *currCtx, asIScriptContext *func);
// Execute each script that is not currently sleeping. The function returns after
// each script has been executed once. The application should call this function
// for each iteration of the message pump, or game loop, or whatever.
// Returns the number of scripts still in execution.
int ExecuteScripts();
// Put a script to sleep for a while
void SetSleeping(asIScriptContext *ctx, asUINT milliSeconds);
// Switch the execution to the next co-routine in the group.
// Returns true if the switch was successful.
void NextCoRoutine();
// Abort all scripts
void AbortAll();
};

# Public script interface

      funcdef void coroutine(dictionary@);
      void createCoRoutine(coroutine @, dictionary @);
      void yield();

funcdef void coroutine(dictionary@)
void createCoRoutine(coroutine @, dictionary @)

This function is used to create a co-routine. The co-routine will initiate in a yielded state, i.e. it will only begin execution once the control is given to it by the current thread.

Multiple co-routines can be created, and they will each take turn to execute in round-robin fashion.

void yield()

Yields control of the execution for the next co-routine in the queue.

When a co-routine receives control it will resume execution from the last call to yield, or the entry point if this is the first time the co-routine is allowed to execute.