/xbmc/visualizations/Vortex/angelscript/docs/doxygen/source/doc_obj_handle.h

  1/**
  2
  3\page doc_obj_handle Object handles
  4
  5
  6In AngelScript an object handle is a reference counted pointer to an object. In the scripts 
  7they are used to pass the objects around by reference instead of by value. Depending on how
  8an application type is registered the type will support handles.
  9
 10\see \ref doc_register_type, \ref doc_script_handle in the script language
 11
 12
 13
 14
 15
 16\section doc_obj_handle_3 Managing the reference counter in functions
 17
 18Whenever the object handle is passed by value from the application to the script engine, 
 19or vice versa its reference should be accounted for. This means that the application must 
 20release any object handles it receives as parameters when it no longer needs them, it also 
 21means that the application must increase the reference counter for any object handle being 
 22returned to the script engine. Note that this is not the same for the \ref doc_generic 
 23"generic calling convention" where AngelScript automatically takes care of most of work.
 24
 25A function that creates an object and returns it to the script engine might look like this:
 26
 27\code
 28// Registered as "obj@ CreateObject()"
 29obj *CreateObject()
 30{
 31  // The constructor already initializes the ref count to 1
 32  return new obj();
 33}
 34\endcode
 35
 36A function that receives an object handle from the script and stores it in a global variable might look like this:
 37
 38\code
 39// Registered as "void StoreObject(obj@)"
 40obj *o = 0;
 41void StoreObject(obj *newO)
 42{
 43  // Release the old object handle
 44  if( o ) o->Release();
 45
 46  // Store the new object handle
 47  o = newO;
 48}
 49\endcode
 50
 51A function that retrieves a previously stored object handle might look like this:
 52
 53\code
 54// Registered as "obj@ RetrieveObject()"
 55obj *RetrieveObject()
 56{
 57  // Increase the reference counter to account for the returned handle
 58  if( o ) o->AddRef();
 59
 60  // It is ok to return null if there is no previous handle stored
 61  return o;
 62}
 63\endcode
 64
 65A function that receives an object handle in the parameter, but doesn't store it looks like this:
 66
 67\code
 68// Registered as "void DoSomething(obj@)"
 69void DoSomething(obj *o)
 70{
 71  // When finished with the object it must be released
 72  if( o ) o->Release();
 73}
 74\endcode
 75
 76
 77
 78
 79
 80\section doc_obj_handle_4 Auto handles can make it easier
 81
 82The application can use auto handles (\@+) to alleviate some of the work of managing the reference counter. 
 83When registering the function or method with AngelScript, add a plus sign to the object handles that 
 84AngelScript should automatically manage. For parameters AngelScript will then release the reference after 
 85the function returns, and for the return value AngelScript will increase the reference on the returned 
 86pointer. The reference for the returned value is increased before the parameters are released, so it is 
 87possible to have the function return one of the parameters.
 88
 89\code
 90// Registered as "obj@+ ChooseObj(obj@+, obj@+)"
 91obj *ChooseObj(obj *a, obj *b)
 92{
 93  // Because of the auto handles AngelScript will
 94  // automatically manage the reference counters
 95  return some_condition ? a : b;
 96}
 97\endcode
 98
 99However, it is not recommended to use this feature unless you can't change the functions you want 
100to register to properly handle the reference counters. When using the auto handles, AngelScript 
101needs to process all of the handles which causes an extra overhead when calling application registered functions.
102
103The auto handles does not affect the behaviour of the handles when the \ref doc_generic "generic calling convention" is used.
104
105*/