/xbmc/visualizations/Vortex/angelscript/docs/manual/doc_obj_handle.html

http://github.com/xbmc/xbmc · HTML · 69 lines · 66 code · 2 blank · 1 comment · 0 complexity · 5e5a4d60403a533214cf980a2bf9bd64 MD5 · raw file 

    

  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
    2. 

  2. <html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
    3. 

  3. <title>AngelScript: Object handles</title>
    4. 

  4. <link href="tabs.css" rel="stylesheet" type="text/css">
    5. 

  5. <link href="doxygen.css" rel="stylesheet" type="text/css">
    6. 

  6. </head><body>
    7. 

  7. <!-- Generated by Doxygen 1.5.9 -->
    8. 

  8. <div class="contents">
    9. 

  9. <h1><a class="anchor" name="doc_obj_handle">Object handles </a></h1>In AngelScript an object handle is a reference counted pointer to an object. In the scripts they are used to pass the objects around by reference instead of by value. Depending on how an application type is registered the type will support handles.<p>
    10. 

  10. <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="doc_register_type.html">Registering an object type</a>, <a class="el" href="doc_script_handle.html">Object handles</a> in the script language</dd></dl>
    11. 

  11. <h2><a class="anchor" name="doc_obj_handle_3">
    12. 

  12. Managing the reference counter in functions</a></h2>
    13. 

  13. Whenever the object handle is passed by value from the application to the script engine, or vice versa its reference should be accounted for. This means that the application must release any object handles it receives as parameters when it no longer needs them, it also means that the application must increase the reference counter for any object handle being returned to the script engine. Note that this is not the same for the <a class="el" href="doc_generic.html">generic calling convention</a> where AngelScript automatically takes care of most of work.<p>
    14. 

  14. A function that creates an object and returns it to the script engine might look like this:<p>
    15. 

  15. <div class="fragment"><pre class="fragment"><span class="comment">// Registered as "obj@ CreateObject()"</span>
    16. 

  16. obj *CreateObject()
    17. 

  17. {
    18. 

  18.   <span class="comment">// The constructor already initializes the ref count to 1</span>
    19. 

  19.   <span class="keywordflow">return</span> <span class="keyword">new</span> obj();
    20. 

  20. }
    21. 

  21. </pre></div><p>
    22. 

  22. A function that receives an object handle from the script and stores it in a global variable might look like this:<p>
    23. 

  23. <div class="fragment"><pre class="fragment"><span class="comment">// Registered as "void StoreObject(obj@)"</span>
    24. 

  24. obj *o = 0;
    25. 

  25. <span class="keywordtype">void</span> StoreObject(obj *newO)
    26. 

  26. {
    27. 

  27.   <span class="comment">// Release the old object handle</span>
    28. 

  28.   <span class="keywordflow">if</span>( o ) o-&gt;Release();
    29. 

  29. 

  30.   <span class="comment">// Store the new object handle</span>
    31. 

  31.   o = newO;
    32. 

  32. }
    33. 

  33. </pre></div><p>
    34. 

  34. A function that retrieves a previously stored object handle might look like this:<p>
    35. 

  35. <div class="fragment"><pre class="fragment"><span class="comment">// Registered as "obj@ RetrieveObject()"</span>
    36. 

  36. obj *RetrieveObject()
    37. 

  37. {
    38. 

  38.   <span class="comment">// Increase the reference counter to account for the returned handle</span>
    39. 

  39.   <span class="keywordflow">if</span>( o ) o-&gt;AddRef();
    40. 

  40. 

  41.   <span class="comment">// It is ok to return null if there is no previous handle stored</span>
    42. 

  42.   <span class="keywordflow">return</span> o;
    43. 

  43. }
    44. 

  44. </pre></div><p>
    45. 

  45. A function that receives an object handle in the parameter, but doesn't store it looks like this:<p>
    46. 

  46. <div class="fragment"><pre class="fragment"><span class="comment">// Registered as "void DoSomething(obj@)"</span>
    47. 

  47. <span class="keywordtype">void</span> DoSomething(obj *o)
    48. 

  48. {
    49. 

  49.   <span class="comment">// When finished with the object it must be released</span>
    50. 

  50.   <span class="keywordflow">if</span>( o ) o-&gt;Release();
    51. 

  51. }
    52. 

  52. </pre></div><h2><a class="anchor" name="doc_obj_handle_4">
    53. 

  53. Auto handles can make it easier</a></h2>
    54. 

  54. The application can use auto handles (@+) to alleviate some of the work of managing the reference counter. When registering the function or method with AngelScript, add a plus sign to the object handles that AngelScript should automatically manage. For parameters AngelScript will then release the reference after the function returns, and for the return value AngelScript will increase the reference on the returned pointer. The reference for the returned value is increased before the parameters are released, so it is possible to have the function return one of the parameters.<p>
    55. 

  55. <div class="fragment"><pre class="fragment"><span class="comment">// Registered as "obj@+ ChooseObj(obj@+, obj@+)"</span>
    56. 

  56. obj *ChooseObj(obj *a, obj *b)
    57. 

  57. {
    58. 

  58.   <span class="comment">// Because of the auto handles AngelScript will</span>
    59. 

  59.   <span class="comment">// automatically manage the reference counters</span>
    60. 

  60.   <span class="keywordflow">return</span> some_condition ? a : b;
    61. 

  61. }
    62. 

  62. </pre></div><p>
    63. 

  63. However, it is not recommended to use this feature unless you can't change the functions you want to register to properly handle the reference counters. When using the auto handles, AngelScript needs to process all of the handles which causes an extra overhead when calling application registered functions.<p>
    64. 

  64. The auto handles does not affect the behaviour of the handles when the <a class="el" href="doc_generic.html">generic calling convention</a> is used. </div>
    65. 

  65. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Dec 16 19:34:51 2009 for AngelScript by&nbsp;
    66. 

  66. <a href="http://www.doxygen.org/index.html">
    67. 

  67. <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.9 </small></address>
    68. 

  68. </body>
    69. 

  69. </html>
    70.