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

http://github.com/xbmc/xbmc · C++ Header · 105 lines · 0 code · 0 blank · 105 comment · 0 complexity · e8d997f078e88ddbcb18f7fd91f2a73a MD5 · raw file

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