192 lines
17 KiB
HTML
192 lines
17 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
|
|
<meta name="generator" content="Doxygen 1.9.6"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>AngelScript: Weak references</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="resize.js"></script>
|
|
<script type="text/javascript" src="navtreedata.js"></script>
|
|
<script type="text/javascript" src="navtree.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(document).ready(function() { init_search(); });
|
|
/* @license-end */
|
|
</script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr id="projectrow">
|
|
<td id="projectlogo"><img alt="Logo" src="aslogo_small.png"/></td>
|
|
<td id="projectalign">
|
|
<div id="projectname">AngelScript
|
|
</div>
|
|
</td>
|
|
<td> <div id="MSearchBox" class="MSearchBoxInactive">
|
|
<span class="left">
|
|
<span id="MSearchSelect" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()"> </span>
|
|
<input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
|
|
onfocus="searchBox.OnSearchFieldFocus(true)"
|
|
onblur="searchBox.OnSearchFieldFocus(false)"
|
|
onkeyup="searchBox.OnSearchFieldChange(event)"/>
|
|
</span><span class="right">
|
|
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
|
|
</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.9.6 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
|
/* @license-end */
|
|
</script>
|
|
</div><!-- top -->
|
|
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
|
<div id="nav-tree">
|
|
<div id="nav-tree-contents">
|
|
<div id="nav-sync" class="sync"></div>
|
|
</div>
|
|
</div>
|
|
<div id="splitbar" style="-moz-user-select:none;"
|
|
class="ui-resizable-handle">
|
|
</div>
|
|
</div>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(document).ready(function(){initNavTree('doc_adv_weakref.html',''); initResizable(); });
|
|
/* @license-end */
|
|
</script>
|
|
<div id="doc-content">
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<div id="MSearchResults">
|
|
<div class="SRPage">
|
|
<div id="SRIndex">
|
|
<div id="SRResults"></div>
|
|
<div class="SRStatus" id="Loading">Loading...</div>
|
|
<div class="SRStatus" id="Searching">Searching...</div>
|
|
<div class="SRStatus" id="NoMatches">No Matches</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div><div class="header">
|
|
<div class="headertitle"><div class="title">Weak references </div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p>Even though AngelScript uses a <a class="el" href="doc_gc.html">garbage collector</a> to resolve cyclic references weak references may still come in handy. Weak references are especifically useful in scenarios were an object wants to be able to access other objects, but do not want to kept them alive longer than necessary.</p>
|
|
<p>AngelScript supports weak references with the use of shared booleans. The code that wants to keep a weak reference to an object should obtain the weakref flag from that object, which is a shared boolean, and before using the pointer to the object it should check if this flag has been set to indicate that the object is no longer alive.</p>
|
|
<p>Script classes automatically supports weak references without the script writing having to do anything. Application registered types on the other hand must register the behaviour <a class="el" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a7a5e435e88a5fc1dcdee13fce091b081">asBEHAVE_GET_WEAKREF_FLAG</a> and implement the logic to set the flag upon destroying the object.</p>
|
|
<p>The following code shows how to do a thread safe implementation:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">class </span>MyClass</div>
|
|
<div class="line">{</div>
|
|
<div class="line"><span class="keyword">public</span>:</div>
|
|
<div class="line"> MyClass() { refCount = 1; weakRefFlag = 0; }</div>
|
|
<div class="line"> <span class="keywordtype">void</span> AddRef() { <a class="code hl_function" href="group__api__multithread__functions.html#gaf0074d581ac2edd06e63e56e4be52c8e">asAtomicInc</a>(refCount); }</div>
|
|
<div class="line"> <span class="keywordtype">void</span> Release() </div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> <span class="comment">// If the weak ref flag exists it is because someone held a weak ref</span></div>
|
|
<div class="line"> <span class="comment">// and that someone may add a reference to the object at any time. It</span></div>
|
|
<div class="line"> <span class="comment">// is ok to check the existance of the weakRefFlag without locking here</span></div>
|
|
<div class="line"> <span class="comment">// because if the refCount is 1 then no other thread is currently </span></div>
|
|
<div class="line"> <span class="comment">// creating the weakRefFlag.</span></div>
|
|
<div class="line"> <span class="keywordflow">if</span>( refCount == 1 && weakRefFlag )</div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> <span class="comment">// Set the flag to tell others that the object is no longer alive</span></div>
|
|
<div class="line"> <span class="comment">// We must do this before decreasing the refCount to 0 so we don't</span></div>
|
|
<div class="line"> <span class="comment">// end up with a race condition between this thread attempting to </span></div>
|
|
<div class="line"> <span class="comment">// destroy the object and the other that temporary added a strong</span></div>
|
|
<div class="line"> <span class="comment">// ref from the weak ref.</span></div>
|
|
<div class="line"> weakRefFlag->Set(<span class="keyword">true</span>);</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">if</span>( <a class="code hl_function" href="group__api__multithread__functions.html#ga0565bcb53be170dd85ae27a5b6f2b828">asAtomicDec</a>(refCount) == 0 ) </div>
|
|
<div class="line"> <span class="keyword">delete</span> <span class="keyword">this</span>; </div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> <a class="code hl_class" href="classas_i_lockable_shared_bool.html">asILockableSharedBool</a> *GetWeakRefFlag()</div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> <span class="keywordflow">if</span>( !weakRefFlag )</div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> <span class="comment">// Lock globally so no other thread can attempt</span></div>
|
|
<div class="line"> <span class="comment">// to create a shared bool at the same time</span></div>
|
|
<div class="line"> <a class="code hl_function" href="group__api__multithread__functions.html#ga016dbf716a1c761b3f903b92eb8bb580">asAcquireExclusiveLock</a>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// Make sure another thread didn't create the </span></div>
|
|
<div class="line"> <span class="comment">// flag while we waited for the lock</span></div>
|
|
<div class="line"> <span class="keywordflow">if</span>( !weakRefFlag )</div>
|
|
<div class="line"> weakRefFlag = <a class="code hl_function" href="group__api__multithread__functions.html#gaf192ffe898295aff4a76d8f2ced70034">asCreateLockableSharedBool</a>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <a class="code hl_function" href="group__api__multithread__functions.html#ga8a0617637eea3d76e33a52758b2cd49f">asReleaseExclusiveLock</a>();</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">return</span> weakRefFlag;</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keyword">static</span> MyClass *Factory() { <span class="keywordflow">return</span> <span class="keyword">new</span> MyClass(); }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">protected</span>:</div>
|
|
<div class="line"> ~MyClass()</div>
|
|
<div class="line"> {</div>
|
|
<div class="line"> <span class="comment">// Release the weak reference flag that may still</span></div>
|
|
<div class="line"> <span class="comment">// be accessed by the code that holds a weak reference</span></div>
|
|
<div class="line"> <span class="keywordflow">if</span>( weakRefFlag )</div>
|
|
<div class="line"> weakRefFlag->Release();</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordtype">int</span> refCount;</div>
|
|
<div class="line"> <a class="code hl_class" href="classas_i_lockable_shared_bool.html">asILockableSharedBool</a> *weakRefFlag;</div>
|
|
<div class="line">};</div>
|
|
<div class="ttc" id="aclassas_i_lockable_shared_bool_html"><div class="ttname"><a href="classas_i_lockable_shared_bool.html">asILockableSharedBool</a></div><div class="ttdoc">A lockable shared boolean.</div><div class="ttdef"><b>Definition:</b> angelscript.h:4257</div></div>
|
|
<div class="ttc" id="agroup__api__multithread__functions_html_ga016dbf716a1c761b3f903b92eb8bb580"><div class="ttname"><a href="group__api__multithread__functions.html#ga016dbf716a1c761b3f903b92eb8bb580">asAcquireExclusiveLock</a></div><div class="ttdeci">AS_API void asAcquireExclusiveLock()</div><div class="ttdoc">Acquire an exclusive lock.</div></div>
|
|
<div class="ttc" id="agroup__api__multithread__functions_html_ga0565bcb53be170dd85ae27a5b6f2b828"><div class="ttname"><a href="group__api__multithread__functions.html#ga0565bcb53be170dd85ae27a5b6f2b828">asAtomicDec</a></div><div class="ttdeci">AS_API int asAtomicDec(int &value)</div><div class="ttdoc">Decrements the value by one and returns the result as a single atomic instruction.</div></div>
|
|
<div class="ttc" id="agroup__api__multithread__functions_html_ga8a0617637eea3d76e33a52758b2cd49f"><div class="ttname"><a href="group__api__multithread__functions.html#ga8a0617637eea3d76e33a52758b2cd49f">asReleaseExclusiveLock</a></div><div class="ttdeci">AS_API void asReleaseExclusiveLock()</div><div class="ttdoc">Release an exclusive lock.</div></div>
|
|
<div class="ttc" id="agroup__api__multithread__functions_html_gaf0074d581ac2edd06e63e56e4be52c8e"><div class="ttname"><a href="group__api__multithread__functions.html#gaf0074d581ac2edd06e63e56e4be52c8e">asAtomicInc</a></div><div class="ttdeci">AS_API int asAtomicInc(int &value)</div><div class="ttdoc">Increments the value by one and returns the result as a single atomic instruction.</div></div>
|
|
<div class="ttc" id="agroup__api__multithread__functions_html_gaf192ffe898295aff4a76d8f2ced70034"><div class="ttname"><a href="group__api__multithread__functions.html#gaf192ffe898295aff4a76d8f2ced70034">asCreateLockableSharedBool</a></div><div class="ttdeci">AS_API asILockableSharedBool * asCreateLockableSharedBool()</div><div class="ttdoc">Create a lockable shared boolean.</div></div>
|
|
</div><!-- fragment --><p>The <a class="el" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a7a5e435e88a5fc1dcdee13fce091b081">asBEHAVE_GET_WEAKREF_FLAG</a> behaviour for this class is registered like this:</p>
|
|
<div class="fragment"><div class="line">engine->RegisterObjectType(<span class="stringliteral">"MyClass"</span>, 0, <a class="code hl_enumvalue" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa9450e038342b36c745858d2e5ae4b861">asOBJ_REF</a>);</div>
|
|
<div class="line">engine->RegisterObjectBehaviour(<span class="stringliteral">"MyClass"</span>, <a class="code hl_enumvalue" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a1dfa5b72ad69a7bf70636d4fcb1b1d84">asBEHAVE_ADDREF</a>, <span class="stringliteral">"void f()"</span>, <a class="code hl_define" href="angelscript_8h.html#a7345e6b3afabec24efd0ff77886d49a6">asMETHOD</a>(MyClass, AddRef), <a class="code hl_enumvalue" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4aea516c8742acc1edff6a43dc1bb09e96">asCALL_THISCALL</a>);</div>
|
|
<div class="line">engine->RegisterObjectBehaviour(<span class="stringliteral">"MyClass"</span>, <a class="code hl_enumvalue" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a7134ce13c81967191af401a1e5170a0c">asBEHAVE_RELEASE</a>, <span class="stringliteral">"void f()"</span>, <a class="code hl_define" href="angelscript_8h.html#a7345e6b3afabec24efd0ff77886d49a6">asMETHOD</a>(MyClass, Release), <a class="code hl_enumvalue" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4aea516c8742acc1edff6a43dc1bb09e96">asCALL_THISCALL</a>);</div>
|
|
<div class="line">engine->RegisterObjectBehaviour(<span class="stringliteral">"MyClass"</span>, <a class="code hl_enumvalue" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a7a5e435e88a5fc1dcdee13fce091b081">asBEHAVE_GET_WEAKREF_FLAG</a>, <span class="stringliteral">"int &f()"</span>, <a class="code hl_define" href="angelscript_8h.html#a7345e6b3afabec24efd0ff77886d49a6">asMETHOD</a>(MyClass, GetWeakRefFlag), <a class="code hl_enumvalue" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4aea516c8742acc1edff6a43dc1bb09e96">asCALL_THISCALL</a>);</div>
|
|
<div class="ttc" id="aangelscript_8h_html_a3ec92ea3c4762e44c2df788ceccdd1e4aea516c8742acc1edff6a43dc1bb09e96"><div class="ttname"><a href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4aea516c8742acc1edff6a43dc1bb09e96">asCALL_THISCALL</a></div><div class="ttdeci">@ asCALL_THISCALL</div><div class="ttdoc">A thiscall class method.</div><div class="ttdef"><b>Definition:</b> angelscript.h:236</div></div>
|
|
<div class="ttc" id="aangelscript_8h_html_a7345e6b3afabec24efd0ff77886d49a6"><div class="ttname"><a href="angelscript_8h.html#a7345e6b3afabec24efd0ff77886d49a6">asMETHOD</a></div><div class="ttdeci">#define asMETHOD(c, m)</div><div class="ttdoc">Returns an asSFuncPtr representing the class method specified by class and method name.</div><div class="ttdef"><b>Definition:</b> angelscript.h:750</div></div>
|
|
<div class="ttc" id="aangelscript_8h_html_a7e38df5b10ec8cbf2a688f1d114097c5a1dfa5b72ad69a7bf70636d4fcb1b1d84"><div class="ttname"><a href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a1dfa5b72ad69a7bf70636d4fcb1b1d84">asBEHAVE_ADDREF</a></div><div class="ttdeci">@ asBEHAVE_ADDREF</div><div class="ttdoc">AddRef.</div><div class="ttdef"><b>Definition:</b> angelscript.h:370</div></div>
|
|
<div class="ttc" id="aangelscript_8h_html_a7e38df5b10ec8cbf2a688f1d114097c5a7134ce13c81967191af401a1e5170a0c"><div class="ttname"><a href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a7134ce13c81967191af401a1e5170a0c">asBEHAVE_RELEASE</a></div><div class="ttdeci">@ asBEHAVE_RELEASE</div><div class="ttdoc">Release.</div><div class="ttdef"><b>Definition:</b> angelscript.h:372</div></div>
|
|
<div class="ttc" id="aangelscript_8h_html_a7e38df5b10ec8cbf2a688f1d114097c5a7a5e435e88a5fc1dcdee13fce091b081"><div class="ttname"><a href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a7a5e435e88a5fc1dcdee13fce091b081">asBEHAVE_GET_WEAKREF_FLAG</a></div><div class="ttdeci">@ asBEHAVE_GET_WEAKREF_FLAG</div><div class="ttdoc">Obtain weak ref flag.</div><div class="ttdef"><b>Definition:</b> angelscript.h:374</div></div>
|
|
<div class="ttc" id="aangelscript_8h_html_a855d86fa9ee15b9f75e553ee376b5c7aa9450e038342b36c745858d2e5ae4b861"><div class="ttname"><a href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa9450e038342b36c745858d2e5ae4b861">asOBJ_REF</a></div><div class="ttdeci">@ asOBJ_REF</div><div class="ttdoc">A reference type.</div><div class="ttdef"><b>Definition:</b> angelscript.h:254</div></div>
|
|
</div><!-- fragment --><p>The script language doesn't have a built-in syntax for weak references. Instead a standard <a class="el" href="doc_addon_weakref.html">weakref add-on</a> has been implemented to provide this for the applications that wants to provide this support in the scripts. </p>
|
|
</div></div><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
</div><!-- doc-content -->
|
|
<!-- start footer part -->
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
|
<ul>
|
|
<li class="footer">Generated on Sun May 21 2023 10:12:40 for AngelScript by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.6 </li>
|
|
</ul>
|
|
</div>
|
|
</body>
|
|
</html>
|