cpp-taskflow/docs/chapter2.html at master · firedtoad/cpp-taskflow

History

133 lines (131 loc) · 16.3 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>Cpp-Taskflow</title>

$(document).ready(initResizable);

</script>

$(document).ready(function() { init_search(); });

</script>

</head>

<body>

<tbody>

<div id="projectname"><a href="https://github.com/cpp-taskflow/cpp-taskflow">Cpp-Taskflow</a>

</div>

</td>

<img id="MSearchSelect" src="search/mag_sel.png"

onmouseover="return searchBox.OnSearchSelectShow()"

onmouseout="return searchBox.OnSearchSelectHide()"

alt=""/>

<input type="text" id="MSearchField" value="Search" accesskey="S"

onfocus="searchBox.OnSearchFieldFocus(true)"

onblur="searchBox.OnSearchFieldFocus(false)"

onkeyup="searchBox.OnSearchFieldChange(event)"/>

</span><span class="right">

</span>

</div>

</td>

</tr>

</tbody>

</table>

</div>

var searchBox = new SearchBox("searchBox", "search",false,'Search');

</script>

</div>

</div>

<div id="splitbar" style="-moz-user-select:none;"

class="ui-resizable-handle">

</div>

$(document).ready(function(){initNavTree('chapter2.html','');});

</script>

<div id="MSearchSelectWindow"

onmouseover="return searchBox.OnSearchSelectShow()"

onmouseout="return searchBox.OnSearchSelectHide()"

onkeydown="return searchBox.OnSearchSelectKey(event)">

</div>

name="MSearchResults" id="MSearchResults">

</iframe>

</div>

<div class="title">C2: Execute a Taskflow </div> </div>

</div>

<div class="textblock"><p>After you create a task dependency graph, you need to dispatch it to threads for execution. In this chapter, we will show you how to execute a task dependency graph.</p>

Graph and Topology</h1>

<p>Each taskflow object has exactly one graph at a time that represents a set of dependent tasks constructed so far. To execute a graph, you need to create an <em>executor</em> from <a class="el" href="classtf_1_1Executor.html" title="The executor class to run a taskflow graph. ">tf::Executor</a>. An executor manages a set of worker threads and schedules task execution through an efficient <em>work-stealing</em> algorithm. Issuing a call to run a taskflow creates a <em>topology</em>. A topology is a data structure wrapping around a running graph. Each executor object has a list of topologies to keep track of the execution status of running and finished graphs. Users can retrieve this information for graph inspection and debugging.</p>

Create an Executor</h1>

<p>The first step is to create an executor to run a taskflow. <a class="el" href="classtf_1_1Executor.html" title="The executor class to run a taskflow graph. ">tf::Executor</a> takes an unsigned integer to construct an executor of <code>N</code> worker threads. The default value is <a class="elRef" doxygen="/home/twhuang/PhD/Code/cpp-taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/thread/thread/hardware_concurrency.html">std::thread::hardware_concurrency</a>.</p>

<div class="fragment"><div class="line"><a class="code" href="classtf_1_1Executor.html">tf::Executor</a> executor1; <span class="comment">// create an executor of std::thread::hardware_concurrency worker threads</span></div><div class="line"><a class="code" href="classtf_1_1Executor.html">tf::Executor</a> executor2(4); <span class="comment">// create an executor of 4 worker threads</span></div></div><p>An executor can be reused to execute multiple taskflows. In most workloads, you may need only one executor but multiple taskflows to represent parts of a parallel decomposition.</p>

Execute a Taskflow</h1>

<p><a class="el" href="classtf_1_1Executor.html" title="The executor class to run a taskflow graph. ">tf::Executor</a> provides a set of <code>run_*</code> methods, <a class="el" href="classtf_1_1Executor.html#a93d3b5c6f5612c1b32033f2dcd27b2a5" title="runs the taskflow once ">tf::Executor::run</a>, <a class="el" href="classtf_1_1Executor.html#a81e5af6069fbae3069257ff63182b544" title="runs the taskflow for N times ">tf::Executor::run_n</a>, and <a class="el" href="classtf_1_1Executor.html#ad7867f1e6541555de96bdd8f6a6b56b2" title="runs the taskflow multiple times until the predicate becomes true and then invokes a callback ...">tf::Executor::run_until</a> to run a taskflow for one time, multiple times, or until a given predicate evaluates to true. All methods accept an optional callback to invoke after the execution completes, and return a <a class="elRef" doxygen="/home/twhuang/PhD/Code/cpp-taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/thread/shared_future.html">std::shared_future</a> for users to access the execution status. The code below shows several ways to run a taskflow.</p>

<div class="fragment"><div class="line"> 1: <span class="comment">// Declare an executor and a taskflow</span></div><div class="line"> 2: <a class="code" href="classtf_1_1Executor.html">tf::Executor</a> executor;</div><div class="line"> 3: <a class="code" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div><div class="line"> 4:</div><div class="line"> 5: <span class="comment">// Add three tasks into the taskflow</span></div><div class="line"> 6: <a class="code" href="classtf_1_1Task.html">tf::Task</a> A = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([] () { <a class="codeRef" doxygen="/home/twhuang/PhD/Code/cpp-taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> << <span class="stringliteral">"This is TaskA\n"</span>; });</div><div class="line"> 7: <a class="code" href="classtf_1_1Task.html">tf::Task</a> B = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([] () { <a class="codeRef" doxygen="/home/twhuang/PhD/Code/cpp-taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> << <span class="stringliteral">"This is TaskB\n"</span>; });</div><div class="line"> 8: <a class="code" href="classtf_1_1Task.html">tf::Task</a> C = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([] () { <a class="codeRef" doxygen="/home/twhuang/PhD/Code/cpp-taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> << <span class="stringliteral">"This is TaskC\n"</span>; });</div><div class="line"> 9: </div><div class="line">10: <span class="comment">// Build precedence between tasks</span></div><div class="line">11: A.<a class="code" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(B, C); </div><div class="line">12: </div><div class="line">13: <a class="codeRef" doxygen="/home/twhuang/PhD/Code/cpp-taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/thread/shared_future.html">std::shared_future<void></a> fu = executor.<a class="code" href="classtf_1_1Executor.html#a93d3b5c6f5612c1b32033f2dcd27b2a5">run</a>(taskflow);</div><div class="line">14: fu.get(); <span class="comment">// block until the execution completes</span></div><div class="line">15:</div><div class="line">16: executor.<a class="code" href="classtf_1_1Executor.html#a93d3b5c6f5612c1b32033f2dcd27b2a5">run</a>(taskflow, [](){ <a class="codeRef" doxygen="/home/twhuang/PhD/Code/cpp-taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> << <span class="stringliteral">"end of one execution\n"</span>; }).<span class="keyword">get</span>();</div><div class="line">17: executor.<a class="code" href="classtf_1_1Executor.html#a81e5af6069fbae3069257ff63182b544">run_n</a>(taskflow, 4);</div><div class="line">18: executor.<a class="code" href="classtf_1_1Executor.html#ab9aa252f70e9a40020a1e5a89d485b85">wait_for_all</a>(); <span class="comment">// block until all associated executions finish</span></div><div class="line">19: executor.<a class="code" href="classtf_1_1Executor.html#a81e5af6069fbae3069257ff63182b544">run_n</a>(taskflow, 4, [](){ <a class="codeRef" doxygen="/home/twhuang/PhD/Code/cpp-taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> << <span class="stringliteral">"end of four executions\n"</span>; }).<span class="keyword">get</span>();</div><div class="line">20: executor.<a class="code" href="classtf_1_1Executor.html#ad7867f1e6541555de96bdd8f6a6b56b2">run_until</a>(taskflow, [<span class="keywordtype">int</span> cnt=0] () <span class="keyword">mutable</span> { <span class="keywordflow">return</span> (++cnt == 10); });</div></div><p>Debrief:</p>

<ul>

<li>Line 6-8 creates a taskflow of three tasks A, B, and C </li>

<li>Line 13-14 runs the taskflow once and use <a class="elRef" doxygen="/home/twhuang/PhD/Code/cpp-taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/thread/shared_future/get.html">std::shared_future::get</a> to wait for completion </li>

<li>Line 16 runs the taskflow once with a callback to invoke when the execution finishes </li>

<li>Line 17-18 runs the taskflow four times and use tf::Taskflow::wait_for_all to wait for completion </li>

<li>Line 19 runs the taskflow four times and invokes a callback at the end of the forth execution </li>

<li>Line 20 keeps running the taskflow until the predicate returns true</li>

</ul>

<p>Issuing multiple runs on a same taskflow will automatically <em>synchronize</em> to a sequential chain of executions following the order of the run calls.</p>

<div class="fragment"><div class="line">executor.<a class="code" href="classtf_1_1Executor.html#a93d3b5c6f5612c1b32033f2dcd27b2a5">run</a>(taskflow); <span class="comment">// execution 1</span></div><div class="line">executor.<a class="code" href="classtf_1_1Executor.html#a81e5af6069fbae3069257ff63182b544">run_n</a>(taskflow, 10); <span class="comment">// execution 2</span></div><div class="line">executor.<a class="code" href="classtf_1_1Executor.html#a93d3b5c6f5612c1b32033f2dcd27b2a5">run</a>(taskflow); <span class="comment">// execution 3</span></div><div class="line">executor.<a class="code" href="classtf_1_1Executor.html#ab9aa252f70e9a40020a1e5a89d485b85">wait_for_all</a>(); <span class="comment">// execution 1 -> execution 2 -> execution 3</span></div></div><p>A key point to notice is a running taskflow must remain alive during its execution. It is your responsibility to ensure a taskflow not being destructed when it is running. For example, the code below can result undefined behavior.</p>

<div class="fragment"><div class="line"><a class="code" href="classtf_1_1Executor.html">tf::Executor</a> executor; <span class="comment">// create an executor</span></div><div class="line"></div><div class="line"><span class="comment">// create a taskflow whose lifetime is restricted by the scope</span></div><div class="line">{</div><div class="line"> <a class="code" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div><div class="line"> </div><div class="line"> <span class="comment">// add tasks to the taskflow</span></div><div class="line"> <span class="comment">// ... </span></div><div class="line"></div><div class="line"> <span class="comment">// run the taskflow</span></div><div class="line"> executor.<a class="code" href="classtf_1_1Executor.html#a93d3b5c6f5612c1b32033f2dcd27b2a5">run</a>(f);</div><div class="line"></div><div class="line">} <span class="comment">// at this point, taskflow might get destructed while it is running, resulting in defined behavior</span></div></div><p>Similarly, you should avoid touching a taskflow while it is running.</p>

<div class="fragment"><div class="line"><a class="code" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div><div class="line"></div><div class="line"><span class="comment">// Add tasks into the taskflow</span></div><div class="line"><span class="comment">// ...</span></div><div class="line"></div><div class="line"><span class="comment">// Declare an executor</span></div><div class="line"><a class="code" href="classtf_1_1Executor.html">tf::Executor</a> executor;</div><div class="line"></div><div class="line"><a class="codeRef" doxygen="/home/twhuang/PhD/Code/cpp-taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/thread/shared_future.html">std::shared_future<void></a> future = taskflow.run(f); <span class="comment">// non-blocking return</span></div><div class="line"></div><div class="line"><span class="comment">// alter the taskflow while running leads to undefined behavior </span></div><div class="line">f.<a class="code" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){ <a class="codeRef" doxygen="/home/twhuang/PhD/Code/cpp-taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> << <span class="stringliteral">"Add a new task\n"</span>; });</div></div><p>A rule of thumb is to always keep a taskflow alive in your function scope while it is participating in an execution. </p>

</div></div>

</div>

<ul>

<li class="footer">Generated by

</ul>

</div>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

chapter2.html

Latest commit

History

chapter2.html

File metadata and controls