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

See also

Co-routines