398 lines
41 KiB
HTML
398 lines
41 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.13.2"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>EnTT: Crash Course: events, signals and everything in between</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>
|
|
<script type="text/javascript" src="clipboard.js"></script>
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="resize.js"></script>
|
|
<script type="text/javascript" src="cookie.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>
|
|
<link href="doxygen-awesome.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="projectalign">
|
|
<div id="projectname">EnTT<span id="projectnumber"> 3.15.0</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.13.2 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
|
/* @license-end */
|
|
</script>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(function() { codefold.init(0); });
|
|
/* @license-end */
|
|
</script>
|
|
<script type="text/javascript" src="menudata.js"></script>
|
|
<script type="text/javascript" src="menu.js"></script>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search',false);
|
|
$(function() { init_search(); });
|
|
});
|
|
/* @license-end */
|
|
</script>
|
|
<div id="main-nav"></div>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(function(){ initResizable(false); });
|
|
/* @license-end */
|
|
</script>
|
|
<!-- 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><!-- top -->
|
|
<div id="doc-content">
|
|
<div><div class="header">
|
|
<div class="headertitle"><div class="title">Crash Course: events, signals and everything in between</div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p><a class="anchor" id="crash-course-events-signals-and-everything-in-between"></a></p>
|
|
<h1><a class="anchor" id="table-of-contents-14"></a>
|
|
Table of Contents</h1>
|
|
<ul>
|
|
<li><a class="el" href="md_docs_2md_2config.html#introduction">Introduction</a></li>
|
|
<li><a class="el" href="#delegate">Delegate</a><ul>
|
|
<li><a class="el" href="#runtime-arguments">Runtime arguments</a></li>
|
|
<li><a class="el" href="#lambda-support">Lambda support</a></li>
|
|
<li><a class="el" href="#raw-access">Raw access</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#signals">Signals</a></li>
|
|
<li><a class="el" href="#event-dispatcher">Event dispatcher</a><ul>
|
|
<li><a class="el" href="#named-queues">Named queues</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#event-emitter">Event emitter</a></li>
|
|
</ul>
|
|
<h1><a class="anchor" id="introduction-13"></a>
|
|
Introduction</h1>
|
|
<p>Signals are more often than not a core part of games and software architectures in general.<br />
|
|
They help to decouple the various parts of a system while allowing them to communicate with each other somehow.</p>
|
|
<p>The so-called <em>modern C++</em> comes with a tool that can be useful in this regard, the <code>std::function</code>. As an example, it can be used to create delegates.<br />
|
|
However, there is no guarantee that an <code>std::function</code> does not perform allocations under the hood and this could be problematic sometimes. Furthermore, it solves a problem but may not adapt well to other requirements that may arise from time to time.</p>
|
|
<p>In case that the flexibility and power of an <code>std::function</code> is not required or if the price to pay for them is too high, <code>EnTT</code> offers a complete set of lightweight classes to solve the same and many other problems.</p>
|
|
<h1><a class="anchor" id="delegate"></a>
|
|
Delegate</h1>
|
|
<p>A delegate can be used as a general purpose invoker with no memory overhead for free functions, lambdas and members provided along with an instance on which to invoke them.<br />
|
|
It does not claim to be a drop-in replacement for an <code>std::function</code>, so do not expect to use it whenever an <code>std::function</code> fits well. That said, it is most likely even a better fit than an <code>std::function</code> in a lot of cases, so expect to use it quite a lot anyway.</p>
|
|
<p>The interface is trivial. It offers a default constructor to create empty delegates:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_class" href="classentt_1_1delegate.html">entt::delegate</a><int(<span class="keywordtype">int</span>)> delegate{};</div>
|
|
<div class="ttc" id="aclassentt_1_1delegate_html"><div class="ttname"><a href="classentt_1_1delegate.html">entt::delegate</a></div><div class="ttdoc">Basic delegate implementation.</div><div class="ttdef"><b>Definition</b> <a href="delegate_8hpp_source.html#l00051">delegate.hpp:51</a></div></div>
|
|
</div><!-- fragment --><p>What is needed to create an instance is to specify the type of the function the delegate <em>accepts</em>, that is the signature of the functions it models.<br />
|
|
However, attempting to use an empty delegate by invoking its function call operator results in undefined behavior or most likely a crash.</p>
|
|
<p>There exist a few overloads of the <code>connect</code> member function to initialize a delegate:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">int</span> f(<span class="keywordtype">int</span> i) { <span class="keywordflow">return</span> i; }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">struct </span>my_struct {</div>
|
|
<div class="line"> <span class="keywordtype">int</span> f(<span class="keyword">const</span> <span class="keywordtype">int</span> &i)<span class="keyword"> const </span>{ <span class="keywordflow">return</span> i; }</div>
|
|
<div class="line">};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// bind a free function to the delegate</span></div>
|
|
<div class="line"><a class="code hl_function" href="namespaceentt.html#acaa5569564e913ef41b15b06e3dca0f4">delegate</a>.connect<&f>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// bind a member function to the delegate</span></div>
|
|
<div class="line">my_struct instance;</div>
|
|
<div class="line"><a class="code hl_function" href="namespaceentt.html#acaa5569564e913ef41b15b06e3dca0f4">delegate</a>.connect<&my_struct::f>(instance);</div>
|
|
<div class="ttc" id="anamespaceentt_html_acaa5569564e913ef41b15b06e3dca0f4"><div class="ttname"><a href="namespaceentt.html#acaa5569564e913ef41b15b06e3dca0f4">entt::delegate</a></div><div class="ttdeci">delegate(connect_arg_t< Candidate >) -> delegate< std::remove_pointer_t< internal::function_pointer_t< decltype(Candidate)> > ></div><div class="ttdoc">Deduction guide.</div></div>
|
|
</div><!-- fragment --><p>The delegate class also accepts data members, if needed. In this case, the function type of the delegate is such that the parameter list is empty and the value of the data member is at least convertible to the return type.</p>
|
|
<p>Free functions having type equivalent to <code>void(T &, args...)</code> are accepted as well. The first argument <code>T &</code> is considered a payload, and the function will receive it back every time it is invoked. In other terms, this works just fine with the above definition:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">void</span> g(<span class="keyword">const</span> <span class="keywordtype">char</span> &c, <span class="keywordtype">int</span> i) { <span class="comment">/* ... */</span> }</div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> c = <span class="charliteral">'c'</span>;</div>
|
|
<div class="line"> </div>
|
|
<div class="line">delegate.connect<&g>(c);</div>
|
|
<div class="line">delegate(42);</div>
|
|
</div><!-- fragment --><p>Function <code>g</code> is invoked with a reference to <code>c</code> and <code>42</code>. However, the function type of the delegate is still <code>void(int)</code>. This is also the signature of its function call operator.<br />
|
|
Another interesting aspect of the delegate class is that it accepts functions with a list of parameters that is shorter than that of its function type:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">void</span> g() { <span class="comment">/* ... */</span> }</div>
|
|
<div class="line">delegate.connect<&g>();</div>
|
|
<div class="line">delegate(42);</div>
|
|
</div><!-- fragment --><p>Where the function type of the delegate is <code>void(int)</code> as above. It goes without saying that the extra arguments are silently discarded internally. This is a nice-to-have feature in a lot of cases, as an example when the <code>delegate</code> class is used as a building block of a signal-slot system.<br />
|
|
In fact, this filtering works both ways. The class tries to pass its first <em>count</em> arguments <b>first</b>, then the last <em>count</em>. Watch out for conversion rules if in doubt when connecting a listener!<br />
|
|
Arbitrary functions that pull random arguments from the delegate list are not supported instead. Other features were preferred, such as support for functions with compatible argument lists although not equal to those of the delegate.</p>
|
|
<p>To create and initialize a delegate at once, there are a few specialized constructors. Because of the rules of the language, the listener is provided by means of the <code><a class="el" href="namespaceentt.html#a142bebb2be3b87a778b1932b3a267a57" title="Constant of type connect_arg_t used to disambiguate calls.">entt::connect_arg</a></code> variable template:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_class" href="classentt_1_1delegate.html">entt::delegate</a><int(<span class="keywordtype">int</span>)> func{<a class="code hl_variable" href="namespaceentt.html#a142bebb2be3b87a778b1932b3a267a57">entt::connect_arg<&f></a>};</div>
|
|
<div class="ttc" id="anamespaceentt_html_a142bebb2be3b87a778b1932b3a267a57"><div class="ttname"><a href="namespaceentt.html#a142bebb2be3b87a778b1932b3a267a57">entt::connect_arg</a></div><div class="ttdeci">constexpr connect_arg_t< Candidate > connect_arg</div><div class="ttdoc">Constant of type connect_arg_t used to disambiguate calls.</div><div class="ttdef"><b>Definition</b> <a href="signal_2fwd_8hpp_source.html#l00042">fwd.hpp:42</a></div></div>
|
|
</div><!-- fragment --><p>Aside <code>connect</code>, a <code>disconnect</code> counterpart is not provided. Instead, there exists a <code>reset</code> member function to use to clear a delegate.<br />
|
|
To know if a delegate is empty, it can be used explicitly in every conditional statement:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">if</span>(delegate) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>Finally, to invoke a delegate, the function call operator is the way to go as already shown in the examples above:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> ret = delegate(42);</div>
|
|
</div><!-- fragment --><p>In all cases, listeners do not have to strictly follow the signature of the delegate. As long as a listener can be invoked with the given arguments to yield a result that is convertible to the given result type, everything works just fine.</p>
|
|
<p>As a side note, members of classes may or may not be associated with instances. If they are not, the first argument of the function type must be that of the class on which the members operate, and an instance of this class must obviously be passed when invoking the delegate:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_class" href="classentt_1_1delegate.html">entt::delegate</a><void(my_struct &, <span class="keywordtype">int</span>)> delegate;</div>
|
|
<div class="line">delegate.connect<&my_struct::f>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line">my_struct instance;</div>
|
|
<div class="line">delegate(instance, 42);</div>
|
|
</div><!-- fragment --><p>In this case, it is not possible to <em>deduce</em> the function type since the first argument does not necessarily have to be a reference (for example, it can be a pointer, as well as a const reference).<br />
|
|
Therefore, the function type must be declared explicitly for unbound members.</p>
|
|
<h2><a class="anchor" id="runtime-arguments"></a>
|
|
Runtime arguments</h2>
|
|
<p>The <code>delegate</code> class is meant to be used primarily with template arguments. However, as a consequence of its design, it also offers minimal support for runtime arguments.<br />
|
|
When used like this, some features are not supported though. In particular:</p>
|
|
<ul>
|
|
<li>Curried functions are not accepted.</li>
|
|
<li>Functions with an argument list that differs from that of the delegate are not supported.</li>
|
|
<li>Return type and types of arguments <b>must</b> coincide with those of the delegate and <em>being at least convertible</em> is not enough anymore.</li>
|
|
</ul>
|
|
<p>Moreover, for a given function type <code>Ret(Args...)</code>, the signature of the functions connected at runtime must necessarily be <code>Ret(const void *, Args...)</code>.</p>
|
|
<p>Runtime arguments can be passed both to the constructor of a delegate and to the <code>connect</code> member function. An optional parameter is also accepted in both cases. This argument is used to pass arbitrary user data back and forth as a <code>const void *</code> upon invocation.<br />
|
|
To connect a function to a delegate <em>in the hard way</em>:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">int</span> func(<span class="keyword">const</span> <span class="keywordtype">void</span> *ptr, <span class="keywordtype">int</span> i) { <span class="keywordflow">return</span> *<span class="keyword">static_cast<</span><span class="keyword">const </span><span class="keywordtype">int</span> *<span class="keyword">></span>(ptr) * i; }</div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keywordtype">int</span> value = 42;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// use the constructor ...</span></div>
|
|
<div class="line"><a class="code hl_class" href="classentt_1_1delegate.html">entt::delegate</a> delegate{&func, &value};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ... or the connect member function</span></div>
|
|
<div class="line"><a class="code hl_function" href="namespaceentt.html#acaa5569564e913ef41b15b06e3dca0f4">delegate</a>.connect(&func, &value);</div>
|
|
</div><!-- fragment --><p>The type of the delegate is deduced from the function if possible. In this case, since the first argument is an implementation detail, the deduced function type is <code>int(int)</code>.<br />
|
|
Invoking a delegate built in this way follows the same rules as previously explained.</p>
|
|
<h2><a class="anchor" id="lambda-support"></a>
|
|
Lambda support</h2>
|
|
<p>In general, the <code>delegate</code> class does not fully support lambda functions in all their nuances. The reason is pretty simple: a <code>delegate</code> is not a drop-in replacement for an <code>std::function</code>. Instead, it tries to overcome the problems with the latter.<br />
|
|
That being said, non-capturing lambda functions are supported, even though some features are not available in this case.</p>
|
|
<p>This is a logical consequence of the support for connecting functions at runtime. Therefore, lambda functions undergo the same rules and limitations.<br />
|
|
In fact, since non-capturing lambda functions decay to pointers to functions, they can be used with a <code>delegate</code> as if they were <em>normal functions</em> with optional payload:</p>
|
|
<div class="fragment"><div class="line">my_struct instance;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// use the constructor ...</span></div>
|
|
<div class="line"><a class="code hl_class" href="classentt_1_1delegate.html">entt::delegate</a> delegate{+[](<span class="keyword">const</span> <span class="keywordtype">void</span> *ptr, <span class="keywordtype">int</span> value) {</div>
|
|
<div class="line"> <span class="keywordflow">return</span> <span class="keyword">static_cast<</span><span class="keyword">const </span>my_struct *<span class="keyword">></span>(ptr)->f(value);</div>
|
|
<div class="line">}, &instance};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ... or the connect member function</span></div>
|
|
<div class="line"><a class="code hl_function" href="namespaceentt.html#acaa5569564e913ef41b15b06e3dca0f4">delegate</a>.connect([](<span class="keyword">const</span> <span class="keywordtype">void</span> *ptr, <span class="keywordtype">int</span> value) {</div>
|
|
<div class="line"> <span class="keywordflow">return</span> <span class="keyword">static_cast<</span><span class="keyword">const </span>my_struct *<span class="keyword">></span>(ptr)->f(value);</div>
|
|
<div class="line">}, &instance);</div>
|
|
</div><!-- fragment --><p>As above, the first parameter (<code>const void *</code>) is not part of the function type of the delegate and is used to dispatch arbitrary user data back and forth. In other terms, the function type of the delegate above is <code>int(int)</code>.</p>
|
|
<h2><a class="anchor" id="raw-access"></a>
|
|
Raw access</h2>
|
|
<p>While not recommended, a delegate also allows direct access to the stored callable function target and underlying data, if any.<br />
|
|
This makes it possible to bypass the behavior of the delegate itself and force calls on different instances:</p>
|
|
<div class="fragment"><div class="line">my_struct other;</div>
|
|
<div class="line">delegate.target(&other, 42);</div>
|
|
</div><!-- fragment --><p>It goes without saying that this type of approach is <b>very</b> risky, especially since there is no way of knowing whether the contained function was originally a member function of some class, a free function or a lambda.<br />
|
|
Another possible (and meaningful) use of this feature is that of identifying a particular delegate through its descriptive <em>traits</em> instead.</p>
|
|
<h1><a class="anchor" id="signals"></a>
|
|
Signals</h1>
|
|
<p>Signal handlers work with references to classes, function pointers, and pointers to members. Listeners can be any kind of objects, and users are in charge of connecting and disconnecting them from a signal to avoid crashes due to different lifetimes. On the other side, performance should not be affected that much by the presence of such a signal handler.<br />
|
|
Signals make use of delegates internally, and therefore they undergo the same rules and offer similar functionalities. It may be a good idea to consult the documentation of the <code>delegate</code> class for further information.</p>
|
|
<p>A signal handler is can be used as a private data member without exposing any <em>publish</em> functionality to the clients of a class.<br />
|
|
The basic idea is to impose a clear separation between the signal itself and the <code>sink</code> class, that is a tool to be used to connect and disconnect listeners on the fly.</p>
|
|
<p>The API of a signal handler is straightforward. If a collector is supplied to the signal when something is published, all the values returned by its listeners are literally <em>collected</em> and used later by the caller. Otherwise, the class works just like a plain signal that emits events from time to time.<br />
|
|
To create instances of signal handlers it is sufficient to provide the type of function to which they refer:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_class" href="classentt_1_1sigh.html">entt::sigh</a><void(<span class="keywordtype">int</span>, <span class="keywordtype">char</span>)> signal;</div>
|
|
<div class="ttc" id="aclassentt_1_1sigh_html"><div class="ttname"><a href="classentt_1_1sigh.html">entt::sigh</a></div><div class="ttdoc">Unmanaged signal handler.</div><div class="ttdef"><b>Definition</b> <a href="signal_2fwd_8hpp_source.html#l00025">fwd.hpp:25</a></div></div>
|
|
</div><!-- fragment --><p>Signals offer all the basic functionalities required to know how many listeners they contain (<code>size</code>) or if they contain at least a listener (<code>empty</code>), as well as a function to use to swap handlers (<code>swap</code>).</p>
|
|
<p>Besides them, there are member functions to use both to connect and disconnect listeners in all their forms by means of a sink:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">void</span> foo(<span class="keywordtype">int</span>, <span class="keywordtype">char</span>) { <span class="comment">/* ... */</span> }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">struct </span>listener {</div>
|
|
<div class="line"> <span class="keywordtype">void</span> bar(<span class="keyword">const</span> <span class="keywordtype">int</span> &, <span class="keywordtype">char</span>) { <span class="comment">/* ... */</span> }</div>
|
|
<div class="line">};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ...</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_class" href="classentt_1_1sink.html">entt::sink</a> <a class="code hl_function" href="namespaceentt.html#aebd935c76f0b7bf40958ec43565ea157">sink</a>{signal};</div>
|
|
<div class="line">listener instance;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_function" href="namespaceentt.html#aebd935c76f0b7bf40958ec43565ea157">sink</a>.connect<&foo>();</div>
|
|
<div class="line"><a class="code hl_function" href="namespaceentt.html#aebd935c76f0b7bf40958ec43565ea157">sink</a>.connect<&listener::bar>(instance);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ...</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// disconnects a free function</span></div>
|
|
<div class="line"><a class="code hl_function" href="namespaceentt.html#aebd935c76f0b7bf40958ec43565ea157">sink</a>.disconnect<&foo>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// disconnect a member function of an instance</span></div>
|
|
<div class="line"><a class="code hl_function" href="namespaceentt.html#aebd935c76f0b7bf40958ec43565ea157">sink</a>.disconnect<&listener::bar>(instance);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// disconnect all member functions of an instance, if any</span></div>
|
|
<div class="line"><a class="code hl_function" href="namespaceentt.html#aebd935c76f0b7bf40958ec43565ea157">sink</a>.disconnect(&instance);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// discards all listeners at once</span></div>
|
|
<div class="line"><a class="code hl_function" href="namespaceentt.html#aebd935c76f0b7bf40958ec43565ea157">sink</a>.disconnect();</div>
|
|
<div class="ttc" id="aclassentt_1_1sink_html"><div class="ttname"><a href="classentt_1_1sink.html">entt::sink</a></div><div class="ttdoc">Sink class.</div><div class="ttdef"><b>Definition</b> <a href="signal_2fwd_8hpp_source.html#l00022">fwd.hpp:22</a></div></div>
|
|
<div class="ttc" id="anamespaceentt_html_aebd935c76f0b7bf40958ec43565ea157"><div class="ttname"><a href="namespaceentt.html#aebd935c76f0b7bf40958ec43565ea157">entt::sink</a></div><div class="ttdeci">sink(sigh< Ret(Args...), Allocator > &) -> sink< sigh< Ret(Args...), Allocator > ></div><div class="ttdoc">Deduction guide.</div></div>
|
|
</div><!-- fragment --><p>As shown above, listeners do not have to strictly follow the signature of the signal. As long as a listener can be invoked with the given arguments to yield a result that is convertible to the given return type, everything works just fine.<br />
|
|
In all cases, the <code>connect</code> member function returns by default a <code>connection</code> object to be used as an alternative to break a connection by means of its <code>release</code> member function.<br />
|
|
A <code>scoped_connection</code> can also be created from a connection. In this case, the link is broken automatically as soon as the object goes out of scope.</p>
|
|
<p>Once listeners are attached (or even if there are no listeners at all), events and data in general are published through a signal by means of the <code>publish</code> member function:</p>
|
|
<div class="fragment"><div class="line">signal.publish(42, <span class="charliteral">'c'</span>);</div>
|
|
</div><!-- fragment --><p>To collect data, the <code>collect</code> member function is used instead:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">int</span> f() { <span class="keywordflow">return</span> 0; }</div>
|
|
<div class="line"><span class="keywordtype">int</span> g() { <span class="keywordflow">return</span> 1; }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ...</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_class" href="classentt_1_1sigh.html">entt::sigh</a><int()> signal;</div>
|
|
<div class="line"><a class="code hl_class" href="classentt_1_1sink.html">entt::sink</a> <a class="code hl_function" href="namespaceentt.html#aebd935c76f0b7bf40958ec43565ea157">sink</a>{signal};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_function" href="namespaceentt.html#aebd935c76f0b7bf40958ec43565ea157">sink</a>.connect<&f>();</div>
|
|
<div class="line"><a class="code hl_function" href="namespaceentt.html#aebd935c76f0b7bf40958ec43565ea157">sink</a>.connect<&g>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line">std::vector<int> vec{};</div>
|
|
<div class="line">signal.collect([&vec](<span class="keywordtype">int</span> value) { vec.push_back(value); });</div>
|
|
<div class="line"> </div>
|
|
<div class="line">assert(vec[0] == 0);</div>
|
|
<div class="line">assert(vec[1] == 1);</div>
|
|
</div><!-- fragment --><p>A collector must expose a function operator that accepts as an argument a type to which the return type of the listeners can be converted. Moreover, it can optionally return a boolean value that is true to stop collecting data, false otherwise. This way one can avoid calling all the listeners in case it is not necessary.<br />
|
|
Functors can also be used in place of a lambda. Since the collector is copied when invoking the <code>collect</code> member function, <code>std::ref</code> is the way to go in this case:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">struct </span>my_collector {</div>
|
|
<div class="line"> std::vector<int> vec{};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordtype">bool</span> operator()(<span class="keywordtype">int</span> v) {</div>
|
|
<div class="line"> vec.push_back(v);</div>
|
|
<div class="line"> <span class="keywordflow">return</span> <span class="keyword">true</span>;</div>
|
|
<div class="line"> }</div>
|
|
<div class="line">};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ...</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line">my_collector collector;</div>
|
|
<div class="line">signal.collect(std::ref(collector));</div>
|
|
</div><!-- fragment --><h1><a class="anchor" id="event-dispatcher"></a>
|
|
Event dispatcher</h1>
|
|
<p>The event dispatcher class allows users to trigger immediate events or to queue and publish them all together later.<br />
|
|
This class lazily instantiates its queues. Therefore, it is not necessary to <em>announce</em> the event types in advance:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// define a general purpose dispatcher</span></div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#a0a861217be8dba074e93e11eaf9bfe0c">entt::dispatcher</a> dispatcher{};</div>
|
|
<div class="ttc" id="anamespaceentt_html_a0a861217be8dba074e93e11eaf9bfe0c"><div class="ttname"><a href="namespaceentt.html#a0a861217be8dba074e93e11eaf9bfe0c">entt::dispatcher</a></div><div class="ttdeci">basic_dispatcher<> dispatcher</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition</b> <a href="signal_2fwd_8hpp_source.html#l00028">fwd.hpp:28</a></div></div>
|
|
</div><!-- fragment --><p>A listener registered with a dispatcher is such that its type offers one or more member functions that take arguments of type <code>Event &</code> for any type of event, regardless of the return value.<br />
|
|
These functions are linked directly via <code>connect</code> to a <em>sink</em>:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">struct </span>an_event { <span class="keywordtype">int</span> value; };</div>
|
|
<div class="line"><span class="keyword">struct </span>another_event {};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">struct </span>listener {</div>
|
|
<div class="line"> <span class="keywordtype">void</span> receive(<span class="keyword">const</span> an_event &) { <span class="comment">/* ... */</span> }</div>
|
|
<div class="line"> <span class="keywordtype">void</span> method(<span class="keyword">const</span> another_event &) { <span class="comment">/* ... */</span> }</div>
|
|
<div class="line">};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ...</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line">listener listener;</div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#a0a861217be8dba074e93e11eaf9bfe0c">dispatcher</a>.<a class="code hl_function" href="classentt_1_1basic__dispatcher.html#a2e76cd8379d9783423255c5d849dfd84">sink</a><an_event>().connect<&listener::receive>(listener);</div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#a0a861217be8dba074e93e11eaf9bfe0c">dispatcher</a>.<a class="code hl_function" href="classentt_1_1basic__dispatcher.html#a2e76cd8379d9783423255c5d849dfd84">sink</a><another_event>().connect<&listener::method>(listener);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__dispatcher_html_a2e76cd8379d9783423255c5d849dfd84"><div class="ttname"><a href="classentt_1_1basic__dispatcher.html#a2e76cd8379d9783423255c5d849dfd84">entt::basic_dispatcher::sink</a></div><div class="ttdeci">auto sink(const id_type id=type_hash< Type >::value())</div><div class="ttdoc">Returns a sink object for the given event and queue.</div><div class="ttdef"><b>Definition</b> <a href="dispatcher_8hpp_source.html#l00264">dispatcher.hpp:264</a></div></div>
|
|
</div><!-- fragment --><p>Note that connecting listeners within event handlers can result in undefined behavior.<br />
|
|
The <code>disconnect</code> member function is used to remove one listener at a time or all of them at once:</p>
|
|
<div class="fragment"><div class="line">dispatcher.<a class="code hl_function" href="classentt_1_1basic__dispatcher.html#a2e76cd8379d9783423255c5d849dfd84">sink</a><an_event>().disconnect<&listener::receive>(listener);</div>
|
|
<div class="line">dispatcher.<a class="code hl_function" href="classentt_1_1basic__dispatcher.html#a2e76cd8379d9783423255c5d849dfd84">sink</a><another_event>().disconnect(&listener);</div>
|
|
</div><!-- fragment --><p>The <code>trigger</code> member function serves the purpose of sending an immediate event to all the listeners registered so far:</p>
|
|
<div class="fragment"><div class="line">dispatcher.<a class="code hl_function" href="classentt_1_1basic__dispatcher.html#a106d465a66d82cfa2e664f0e14b498e3">trigger</a>(an_event{42});</div>
|
|
<div class="line">dispatcher.<a class="code hl_function" href="classentt_1_1basic__dispatcher.html#a106d465a66d82cfa2e664f0e14b498e3">trigger</a><another_event>();</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__dispatcher_html_a106d465a66d82cfa2e664f0e14b498e3"><div class="ttname"><a href="classentt_1_1basic__dispatcher.html#a106d465a66d82cfa2e664f0e14b498e3">entt::basic_dispatcher::trigger</a></div><div class="ttdeci">void trigger(Type &&value={})</div><div class="ttdoc">Triggers an immediate event of a given type.</div><div class="ttdef"><b>Definition</b> <a href="dispatcher_8hpp_source.html#l00274">dispatcher.hpp:274</a></div></div>
|
|
</div><!-- fragment --><p>Listeners are invoked immediately, order of execution is not guaranteed. This method can be used to push around urgent messages like an <em>is terminating</em> notification on a mobile app.</p>
|
|
<p>On the other hand, the <code>enqueue</code> member function queues messages together and helps to maintain control over the moment they are sent to listeners:</p>
|
|
<div class="fragment"><div class="line">dispatcher.<a class="code hl_function" href="classentt_1_1basic__dispatcher.html#aefeb6cfbb14cf16ad7bee0148a324867">enqueue</a><an_event>(42);</div>
|
|
<div class="line">dispatcher.<a class="code hl_function" href="classentt_1_1basic__dispatcher.html#aefeb6cfbb14cf16ad7bee0148a324867">enqueue</a>(another_event{});</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__dispatcher_html_aefeb6cfbb14cf16ad7bee0148a324867"><div class="ttname"><a href="classentt_1_1basic__dispatcher.html#aefeb6cfbb14cf16ad7bee0148a324867">entt::basic_dispatcher::enqueue</a></div><div class="ttdeci">void enqueue(Args &&...args)</div><div class="ttdoc">Enqueues an event of the given type.</div><div class="ttdef"><b>Definition</b> <a href="dispatcher_8hpp_source.html#l00296">dispatcher.hpp:296</a></div></div>
|
|
</div><!-- fragment --><p>Events are stored aside until the <code>update</code> member function is invoked:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// emits all the events of the given type at once</span></div>
|
|
<div class="line">dispatcher.<a class="code hl_function" href="classentt_1_1basic__dispatcher.html#a7d0b2fc6d403b187f112798823c870dc">update</a><an_event>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// emits all the events queued so far at once</span></div>
|
|
<div class="line">dispatcher.<a class="code hl_function" href="classentt_1_1basic__dispatcher.html#a7d0b2fc6d403b187f112798823c870dc">update</a>();</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__dispatcher_html_a7d0b2fc6d403b187f112798823c870dc"><div class="ttname"><a href="classentt_1_1basic__dispatcher.html#a7d0b2fc6d403b187f112798823c870dc">entt::basic_dispatcher::update</a></div><div class="ttdeci">void update(const id_type id=type_hash< Type >::value())</div><div class="ttdoc">Delivers all the pending events of a given queue.</div><div class="ttdef"><b>Definition</b> <a href="dispatcher_8hpp_source.html#l00380">dispatcher.hpp:380</a></div></div>
|
|
</div><!-- fragment --><p>This way users can embed the dispatcher in a loop and literally dispatch events once per tick to their systems.</p>
|
|
<h2><a class="anchor" id="named-queues"></a>
|
|
Named queues</h2>
|
|
<p>All queues within a dispatcher are associated by default with an event type and then retrieved from it.<br />
|
|
However, it is possible to create queues with different <em>names</em> (and therefore also multiple queues for a single type). In fact, more or less all functions also take an additional parameter. As an example:</p>
|
|
<div class="fragment"><div class="line">dispatcher.<a class="code hl_function" href="classentt_1_1basic__dispatcher.html#a2e76cd8379d9783423255c5d849dfd84">sink</a><an_event>(<span class="stringliteral">"custom"</span>_hs).connect<&listener::receive>(listener);</div>
|
|
</div><!-- fragment --><p>In this case, the term <em>name</em> is misused as these are actual numeric identifiers of type <code>id_type</code>.<br />
|
|
An exception to this rule is the <code>enqueue</code> function. There is no additional parameter for it but rather a different function:</p>
|
|
<div class="fragment"><div class="line">dispatcher.<a class="code hl_function" href="classentt_1_1basic__dispatcher.html#a3da25e303527faa6f57616a077333681">enqueue_hint</a><an_event>(<span class="stringliteral">"custom"</span>_hs, 42);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__dispatcher_html_a3da25e303527faa6f57616a077333681"><div class="ttname"><a href="classentt_1_1basic__dispatcher.html#a3da25e303527faa6f57616a077333681">entt::basic_dispatcher::enqueue_hint</a></div><div class="ttdeci">void enqueue_hint(const id_type id, Args &&...args)</div><div class="ttdoc">Enqueues an event of the given type.</div><div class="ttdef"><b>Definition</b> <a href="dispatcher_8hpp_source.html#l00318">dispatcher.hpp:318</a></div></div>
|
|
</div><!-- fragment --><p>This is mainly due to the template argument deduction rules, and there is no real (elegant) way to avoid it.</p>
|
|
<h1><a class="anchor" id="event-emitter"></a>
|
|
Event emitter</h1>
|
|
<p>A general purpose event emitter thought mainly for those cases where it comes to working with asynchronous stuff.<br />
|
|
Originally designed to fit the requirements of <a href="https://github.com/skypjack/uvw"><code>uvw</code></a> (a wrapper for <code>libuv</code> written in modern C++), it was adapted later to be included in this library.</p>
|
|
<p>To create an emitter type, derived classes must inherit from the base as:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">struct </span>my_emitter: emitter<my_emitter> {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>Handlers for the different events are created internally on the fly. It is not required to specify in advance the full list of accepted events.<br />
|
|
Moreover, whenever an event is published, an emitter also passes a reference to itself to its listeners.</p>
|
|
<p>To create new instances of an emitter, no arguments are required:</p>
|
|
<div class="fragment"><div class="line">my_emitter emitter{};</div>
|
|
</div><!-- fragment --><p>Listeners are movable and callable objects (free functions, lambdas, functors, <code>std::function</code>s, whatever) whose function type is compatible with:</p>
|
|
<div class="fragment"><div class="line">void(Type &, my_emitter &)</div>
|
|
</div><!-- fragment --><p>Where <code>Type</code> is the type of event they want to receive.<br />
|
|
To attach a listener to an emitter, there exists the <code>on</code> member function:</p>
|
|
<div class="fragment"><div class="line">emitter.on<my_event>([](<span class="keyword">const</span> my_event &event, my_emitter &emitter) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">});</div>
|
|
</div><!-- fragment --><p>Similarly, the <code>reset</code> member function is used to disconnect listeners given a type while <code>clear</code> is used to disconnect all listeners at once:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// resets the listener for my_event</span></div>
|
|
<div class="line">emitter.erase<my_event>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// resets all listeners</span></div>
|
|
<div class="line">emitter.clear()</div>
|
|
</div><!-- fragment --><p>To send an event to the listener registered on a given type, the <code>publish</code> function is the way to go:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">struct </span>my_event { <span class="keywordtype">int</span> i; };</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ...</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line">emitter.publish(my_event{42});</div>
|
|
</div><!-- fragment --><p>Finally, the <code>empty</code> member function tests if there exists at least a listener registered with the event emitter while <code>contains</code> is used to check if a given event type is associated with a valid listener:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">if</span>(emitter.contains<my_event>()) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>This class introduces a <em>nice-to-have</em> model based on events and listeners.<br />
|
|
More in general, it is a handy tool when the derived classes <em>wrap</em> asynchronous operations, but it is not limited to such uses. </p>
|
|
</div></div><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
<!-- start footer part -->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.13.2
|
|
</small></address>
|
|
</div><!-- doc-content -->
|
|
</body>
|
|
</html>
|