198 lines
17 KiB
HTML
198 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">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.8.16"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>EnTT: Crash Course: cooperative scheduler</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="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.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 style="height: 56px;">
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
|
<div id="projectname">EnTT
|
|
 <span id="projectnumber">3.3.0</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.8.16 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
/* @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:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search');
|
|
$(document).ready(function() { init_search(); });
|
|
});
|
|
/* @license-end */</script>
|
|
<div id="main-nav"></div>
|
|
<!-- 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">
|
|
<iframe src="javascript:void(0)" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
</div><!-- top -->
|
|
<div class="PageDoc"><div class="header">
|
|
<div class="headertitle">
|
|
<div class="title">Crash Course: cooperative scheduler </div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><h1><a class="anchor" id="autotoc_md83"></a>
|
|
Introduction</h1>
|
|
<p>Sometimes processes are a useful tool to work around the strict definition of a system and introduce logic in a different way, usually without resorting to the introduction of other components.</p>
|
|
<p><code>EnTT</code> offers a minimal support to this paradigm by introducing a few classes that users can use to define and execute cooperative processes.</p>
|
|
<h1><a class="anchor" id="autotoc_md84"></a>
|
|
The process</h1>
|
|
<p>A typical process must inherit from the <code>process</code> class template that stays true to the CRTP idiom. Moreover, derived classes must specify what's the intended type for elapsed times.</p>
|
|
<p>A process should expose publicly the following member functions whether required (note that it isn't required to define a function unless the derived class wants to <em>override</em> the default behavior):</p>
|
|
<ul>
|
|
<li><p class="startli"><code>void update(Delta, void *);</code></p>
|
|
<p class="startli">It's invoked once per tick until a process is explicitly aborted or it terminates either with or without errors. Even though it's not mandatory to declare this member function, as a rule of thumb each process should at least define it to work properly. The <code>void *</code> parameter is an opaque pointer to user data (if any) forwarded directly to the process during an update.</p>
|
|
</li>
|
|
<li><p class="startli"><code>void init();</code></p>
|
|
<p class="startli">It's invoked when the process joins the running queue of a scheduler. This happens as soon as it's attached to the scheduler if the process is a top level one, otherwise when it replaces its parent if the process is a continuation.</p>
|
|
</li>
|
|
<li><p class="startli"><code>void succeeded();</code></p>
|
|
<p class="startli">It's invoked in case of success, immediately after an update and during the same tick.</p>
|
|
</li>
|
|
<li><p class="startli"><code>void failed();</code></p>
|
|
<p class="startli">It's invoked in case of errors, immediately after an update and during the same tick.</p>
|
|
</li>
|
|
<li><p class="startli"><code>void aborted();</code></p>
|
|
<p class="startli">It's invoked only if a process is explicitly aborted. There is no guarantee that it executes in the same tick, this depends solely on whether the process is aborted immediately or not.</p>
|
|
</li>
|
|
</ul>
|
|
<p>Derived classes can also change the internal state of a process by invoking <code>succeed</code> and <code>fail</code>, as well as <code>pause</code> and <code>unpause</code> the process itself. All these are protected member functions made available to be able to manage the life cycle of a process from a derived class.</p>
|
|
<p>Here is a minimal example for the sake of curiosity:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">struct </span>my_process: <a class="code" href="classentt_1_1process.html">entt::process</a><my_process, std::uint32_t> {</div>
|
|
<div class="line"> <span class="keyword">using</span> delta_type = std::uint32_t;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> my_process(delta_type delay)</div>
|
|
<div class="line"> : remaining{delay}</div>
|
|
<div class="line"> {}</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordtype">void</span> update(delta_type delta, <span class="keywordtype">void</span> *) {</div>
|
|
<div class="line"> remaining -= std::min(remaining, delta);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">if</span>(!remaining) {</div>
|
|
<div class="line"> <a class="code" href="classentt_1_1process.html#a43d63ba9304654f0209fc32d2c74f4ce">succeed</a>();</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">private</span>:</div>
|
|
<div class="line"> delta_type remaining;</div>
|
|
<div class="line">};</div>
|
|
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md85"></a>
|
|
Adaptor</h2>
|
|
<p>Lambdas and functors can't be used directly with a scheduler for they are not properly defined processes with managed life cycles.<br />
|
|
This class helps in filling the gap and turning lambdas and functors into full featured processes usable by a scheduler.</p>
|
|
<p>The function call operator has a signature similar to the one of the <code>update</code> function of a process but for the fact that it receives two extra arguments to call whenever a process is terminated with success or with an error:</p>
|
|
<div class="fragment"><div class="line">void(Delta delta, <span class="keywordtype">void</span> *data, <span class="keyword">auto</span> succeed, <span class="keyword">auto</span> fail);</div>
|
|
</div><!-- fragment --><p>Parameters have the following meaning:</p>
|
|
<ul>
|
|
<li><code>delta</code> is the elapsed time.</li>
|
|
<li><code>data</code> is an opaque pointer to user data if any, <code>nullptr</code> otherwise.</li>
|
|
<li><code>succeed</code> is a function to call when a process terminates with success.</li>
|
|
<li><code>fail</code> is a function to call when a process terminates with errors.</li>
|
|
</ul>
|
|
<p>Both <code>succeed</code> and <code>fail</code> accept no parameters at all.</p>
|
|
<p>Note that usually users shouldn't worry about creating adaptors at all. A scheduler creates them internally each and every time a lambda or a functor is used as a process.</p>
|
|
<h1><a class="anchor" id="autotoc_md86"></a>
|
|
The scheduler</h1>
|
|
<p>A cooperative scheduler runs different processes and helps managing their life cycles.</p>
|
|
<p>Each process is invoked once per tick. If it terminates, it's removed automatically from the scheduler and it's never invoked again. Otherwise it's a good candidate to run one more time the next tick.<br />
|
|
A process can also have a child. In this case, the parent process is replaced with its child when it terminates and only if it returns with success. In case of errors, both the parent process and its child are discarded. This way, it's easy to create chain of processes to run sequentially.</p>
|
|
<p>Using a scheduler is straightforward. To create it, users must provide only the type for the elapsed times and no arguments at all:</p>
|
|
<div class="fragment"><div class="line"><a class="code" href="classentt_1_1scheduler.html">entt::scheduler<std::uint32_t></a> scheduler;</div>
|
|
</div><!-- fragment --><p>It has member functions to query its internal data structures, like <code>empty</code> or <code>size</code>, as well as a <code>clear</code> utility to reset it to a clean state:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// checks if there are processes still running</span></div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> empty = scheduler.<a class="code" href="classentt_1_1scheduler.html#a817d93653aec6a479b920143bd21edbb">empty</a>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// gets the number of processes still running</span></div>
|
|
<div class="line"><a class="code" href="classentt_1_1scheduler.html#afcec47d6ec28a994af2a7097348ce59f">entt::scheduler<std::uint32_t>::size_type</a> size = scheduler.<a class="code" href="classentt_1_1scheduler.html#ab0c473e6d4733bdb78f3dc26147de4ad">size</a>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// resets the scheduler to its initial state and discards all the processes</span></div>
|
|
<div class="line">scheduler.<a class="code" href="classentt_1_1scheduler.html#a5a0f92dbe54b58751237a567e86805e0">clear</a>();</div>
|
|
</div><!-- fragment --><p>To attach a process to a scheduler there are mainly two ways:</p>
|
|
<ul>
|
|
<li>If the process inherits from the <code>process</code> class template, it's enough to indicate its type and submit all the parameters required to construct it to the <code>attach</code> member function:</li>
|
|
</ul>
|
|
<div class="fragment"><div class="line">scheduler.<a class="code" href="classentt_1_1scheduler.html#a729c83e1983123c642a08cda67e486e3">attach</a><my_process>(1000u);</div>
|
|
</div><!-- fragment --><ul>
|
|
<li>Otherwise, in case of a lambda or a functor, it's enough to provide an instance of the class to the <code>attach</code> member function:</li>
|
|
</ul>
|
|
<div class="fragment"><div class="line">scheduler.<a class="code" href="classentt_1_1scheduler.html#a729c83e1983123c642a08cda67e486e3">attach</a>([](<span class="keyword">auto</span>...){ <span class="comment">/* ... */</span> });</div>
|
|
</div><!-- fragment --><p>In both cases, the return value is an opaque object that offers a <code>then</code> member function to use to create chains of processes to run sequentially.<br />
|
|
As a minimal example of use:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// schedules a task in the form of a lambda function</span></div>
|
|
<div class="line">scheduler.<a class="code" href="classentt_1_1scheduler.html#a729c83e1983123c642a08cda67e486e3">attach</a>([](<span class="keyword">auto</span> delta, <span class="keywordtype">void</span> *, <span class="keyword">auto</span> succeed, <span class="keyword">auto</span> fail) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">})</div>
|
|
<div class="line"><span class="comment">// appends a child in the form of another lambda function</span></div>
|
|
<div class="line">.then([](<span class="keyword">auto</span> delta, <span class="keywordtype">void</span> *, <span class="keyword">auto</span> succeed, <span class="keyword">auto</span> fail) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">})</div>
|
|
<div class="line"><span class="comment">// appends a child in the form of a process class</span></div>
|
|
<div class="line">.then<my_process>(1000u);</div>
|
|
</div><!-- fragment --><p>To update a scheduler and therefore all its processes, the <code>update</code> member function is the way to go:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// updates all the processes, no user data are provided</span></div>
|
|
<div class="line">scheduler.update(delta);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// updates all the processes and provides them with custom data</span></div>
|
|
<div class="line">scheduler.update(delta, &data);</div>
|
|
</div><!-- fragment --><p>In addition to these functions, the scheduler offers an <code>abort</code> member function that can be used to discard all the running processes at once:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// aborts all the processes abruptly ...</span></div>
|
|
<div class="line">scheduler.abort(<span class="keyword">true</span>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ... or gracefully during the next tick</span></div>
|
|
<div class="line">scheduler.abort();</div>
|
|
</div><!-- fragment --> </div></div><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
<div class="ttc" id="aclassentt_1_1scheduler_html_a5a0f92dbe54b58751237a567e86805e0"><div class="ttname"><a href="classentt_1_1scheduler.html#a5a0f92dbe54b58751237a567e86805e0">entt::scheduler::clear</a></div><div class="ttdeci">void clear()</div><div class="ttdoc">Discards all scheduled processes.</div><div class="ttdef"><b>Definition:</b> <a href="scheduler_8hpp_source.html#l00147">scheduler.hpp:147</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1scheduler_html"><div class="ttname"><a href="classentt_1_1scheduler.html">entt::scheduler</a></div><div class="ttdoc">Cooperative scheduler for processes.</div><div class="ttdef"><b>Definition:</b> <a href="scheduler_8hpp_source.html#l00044">scheduler.hpp:44</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1process_html"><div class="ttname"><a href="classentt_1_1process.html">entt::process</a></div><div class="ttdoc">Base class for processes.</div><div class="ttdef"><b>Definition:</b> <a href="process_8hpp_source.html#l00073">process.hpp:73</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1scheduler_html_afcec47d6ec28a994af2a7097348ce59f"><div class="ttname"><a href="classentt_1_1scheduler.html#afcec47d6ec28a994af2a7097348ce59f">entt::scheduler::size_type</a></div><div class="ttdeci">std::size_t size_type</div><div class="ttdoc">Unsigned integer type.</div><div class="ttdef"><b>Definition:</b> <a href="scheduler_8hpp_source.html#l00114">scheduler.hpp:114</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1scheduler_html_a817d93653aec6a479b920143bd21edbb"><div class="ttname"><a href="classentt_1_1scheduler.html#a817d93653aec6a479b920143bd21edbb">entt::scheduler::empty</a></div><div class="ttdeci">bool empty() const ENTT_NOEXCEPT</div><div class="ttdoc">Returns true if at least a process is currently scheduled.</div><div class="ttdef"><b>Definition:</b> <a href="scheduler_8hpp_source.html#l00137">scheduler.hpp:137</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1scheduler_html_a729c83e1983123c642a08cda67e486e3"><div class="ttname"><a href="classentt_1_1scheduler.html#a729c83e1983123c642a08cda67e486e3">entt::scheduler::attach</a></div><div class="ttdeci">auto attach(Args &&... args)</div><div class="ttdoc">Schedules a process for the next tick.</div><div class="ttdef"><b>Definition:</b> <a href="scheduler_8hpp_source.html#l00177">scheduler.hpp:177</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1scheduler_html_ab0c473e6d4733bdb78f3dc26147de4ad"><div class="ttname"><a href="classentt_1_1scheduler.html#ab0c473e6d4733bdb78f3dc26147de4ad">entt::scheduler::size</a></div><div class="ttdeci">size_type size() const ENTT_NOEXCEPT</div><div class="ttdoc">Number of processes currently scheduled.</div><div class="ttdef"><b>Definition:</b> <a href="scheduler_8hpp_source.html#l00129">scheduler.hpp:129</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1process_html_a43d63ba9304654f0209fc32d2c74f4ce"><div class="ttname"><a href="classentt_1_1process.html#a43d63ba9304654f0209fc32d2c74f4ce">entt::process::succeed</a></div><div class="ttdeci">void succeed() ENTT_NOEXCEPT</div><div class="ttdoc">Terminates a process with success if it's still alive.</div><div class="ttdef"><b>Definition:</b> <a href="process_8hpp_source.html#l00127">process.hpp:127</a></div></div>
|
|
<!-- start footer part -->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
Generated by  <a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/>
|
|
</a> 1.8.16
|
|
</small></address>
|
|
</body>
|
|
</html>
|