forked from taskflow/taskflow
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathStaticTasking.xml
More file actions
248 lines (248 loc) · 36.1 KB
/
Copy pathStaticTasking.xml
File metadata and controls
248 lines (248 loc) · 36.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
<?xml version='1.0' encoding='UTF-8' standalone='no'?>
<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="1.12.0" xml:lang="en-US">
<compounddef id="StaticTasking" kind="page">
<compoundname>StaticTasking</compoundname>
<title>Static Tasking</title>
<tableofcontents>
<tocsect>
<name>Create a Task Dependency Graph</name>
<reference>StaticTasking_1CreateATaskDependencyGraph</reference>
</tocsect>
<tocsect>
<name>Visualize a Task Dependency Graph</name>
<reference>StaticTasking_1VisualizeATaskDependencyGraph</reference>
</tocsect>
<tocsect>
<name>Modify Task Attributes</name>
<reference>StaticTasking_1ModifyTaskAttributes</reference>
</tocsect>
<tocsect>
<name>Traverse Adjacent Tasks</name>
<reference>StaticTasking_1TraverseAdjacentTasks</reference>
</tocsect>
<tocsect>
<name>Attach User Data to a Task</name>
<reference>StaticTasking_1AttachUserDataToATask</reference>
</tocsect>
<tocsect>
<name>Understand the Lifetime of a Task</name>
<reference>StaticTasking_1UnderstandTheLifetimeOfATask</reference>
</tocsect>
<tocsect>
<name>Move a Taskflow</name>
<reference>StaticTasking_1MoveATaskflow</reference>
</tocsect>
</tableofcontents>
<briefdescription>
</briefdescription>
<detaileddescription>
<para>This chapter demonstrates how to create a static task dependency graph. Static tasking captures the static parallel structure of a decomposition and is defined only by the program itself. It has a flat task hierarchy and cannot spawn new tasks from a running dependency graph.</para>
<sect1 id="StaticTasking_1CreateATaskDependencyGraph">
<title>Create a Task Dependency Graph</title><para>A task in Taskflow is a <emphasis>callable</emphasis> object for which the operation <ulink url="https://en.cppreference.com/w/cpp/utility/functional/invoke">std::invoke</ulink> is applicable. It can be either a functor, a lambda expression, a bind expression, or a class objects with <computeroutput>operator()</computeroutput> overloaded. All tasks are created from <ref refid="classtf_1_1Taskflow" kindref="compound">tf::Taskflow</ref>, the class that manages a task dependency graph. Taskflow provides two methods, <ref refid="classtf_1_1FlowBuilder_1acab0b4ac82260f47fdb36a3244ee3aaf" kindref="member">tf::Taskflow::placeholder</ref> and <ref refid="classtf_1_1FlowBuilder_1a60d7a666cab71ecfa3010b2efb0d6b57" kindref="member">tf::Taskflow::emplace</ref> to create a task.</para>
<para><programlisting filename=".cpp"><codeline><highlight class="normal">1:<sp/><ref refid="classtf_1_1Taskflow" kindref="compound">tf::Taskflow</ref><sp/>taskflow;</highlight></codeline>
<codeline><highlight class="normal">2:<sp/><ref refid="classtf_1_1Task" kindref="compound">tf::Task</ref><sp/>A<sp/>=<sp/>taskflow.<ref refid="classtf_1_1FlowBuilder_1acab0b4ac82260f47fdb36a3244ee3aaf" kindref="member">placeholder</ref>();</highlight></codeline>
<codeline><highlight class="normal">3:<sp/><ref refid="classtf_1_1Task" kindref="compound">tf::Task</ref><sp/>B<sp/>=<sp/>taskflow.<ref refid="classtf_1_1FlowBuilder_1a60d7a666cab71ecfa3010b2efb0d6b57" kindref="member">emplace</ref>([]<sp/>()<sp/>{<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"task<sp/>B\n"</highlight><highlight class="normal">;<sp/>});</highlight></codeline>
<codeline><highlight class="normal">4:</highlight></codeline>
<codeline><highlight class="normal">5:<sp/></highlight><highlight class="keyword">auto</highlight><highlight class="normal"><sp/>[D,<sp/>E,<sp/>F]<sp/>=<sp/>taskflow.<ref refid="classtf_1_1FlowBuilder_1a60d7a666cab71ecfa3010b2efb0d6b57" kindref="member">emplace</ref>(</highlight></codeline>
<codeline><highlight class="normal">6:<sp/><sp/><sp/>[](){<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"Task<sp/>A\n"</highlight><highlight class="normal">;<sp/>},</highlight></codeline>
<codeline><highlight class="normal">7:<sp/><sp/><sp/>[](){<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"Task<sp/>B\n"</highlight><highlight class="normal">;<sp/>},</highlight></codeline>
<codeline><highlight class="normal">8:<sp/><sp/><sp/>[](){<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"Task<sp/>C\n"</highlight><highlight class="normal">;<sp/>}</highlight></codeline>
<codeline><highlight class="normal">9:<sp/>);</highlight></codeline>
</programlisting></para>
<para>Debrief: <itemizedlist>
<listitem><para>Line 1 creates a taskflow object, or a <emphasis>graph</emphasis> </para>
</listitem>
<listitem><para>Line 2 creates a placeholder task without work (i.e., callable) </para>
</listitem>
<listitem><para>Line 3 creates a task from a given callable object and returns a task handle </para>
</listitem>
<listitem><para>Lines 5-9 create three tasks in one call using C++ structured binding coupled with <ref refid="cpp/utility/tuple" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::tuple</ref></para>
</listitem>
</itemizedlist>
Each time you create a task, the taskflow object creates a node in the task graph and returns a task handle of type <ref refid="classtf_1_1Task" kindref="compound">tf::Task</ref>. A task handle is a lightweight object that wraps up a particular node in a graph and provides a set of methods for you to assign different attributes to the task such as adding dependencies, naming, and assigning a new work.</para>
<para><programlisting filename=".cpp"><codeline><highlight class="normal"><sp/>1:<sp/><ref refid="classtf_1_1Taskflow" kindref="compound">tf::Taskflow</ref><sp/>taskflow;</highlight></codeline>
<codeline><highlight class="normal"><sp/>2:<sp/><ref refid="classtf_1_1Task" kindref="compound">tf::Task</ref><sp/>A<sp/>=<sp/>taskflow.<ref refid="classtf_1_1FlowBuilder_1a60d7a666cab71ecfa3010b2efb0d6b57" kindref="member">emplace</ref>([]<sp/>()<sp/>{<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"create<sp/>a<sp/>task<sp/>A\n"</highlight><highlight class="normal">;<sp/>});</highlight></codeline>
<codeline><highlight class="normal"><sp/>3:<sp/><ref refid="classtf_1_1Task" kindref="compound">tf::Task</ref><sp/>B<sp/>=<sp/>taskflow.<ref refid="classtf_1_1FlowBuilder_1a60d7a666cab71ecfa3010b2efb0d6b57" kindref="member">emplace</ref>([]<sp/>()<sp/>{<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"create<sp/>a<sp/>task<sp/>B\n"</highlight><highlight class="normal">;<sp/>});</highlight></codeline>
<codeline><highlight class="normal"><sp/>4:</highlight></codeline>
<codeline><highlight class="normal"><sp/>5:<sp/>A.<ref refid="classtf_1_1Task_1a08ada0425b490997b6ff7f310107e5e3" kindref="member">name</ref>(</highlight><highlight class="stringliteral">"TaskA"</highlight><highlight class="normal">);</highlight></codeline>
<codeline><highlight class="normal"><sp/>6:<sp/>A.<ref refid="classtf_1_1Task_1a2f6f4cec42d016e5eb89390f362ffe99" kindref="member">work</ref>([]<sp/>()<sp/>{<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"reassign<sp/>A<sp/>to<sp/>a<sp/>new<sp/>callable\n"</highlight><highlight class="normal">;<sp/>});</highlight></codeline>
<codeline><highlight class="normal"><sp/>7:<sp/>A.<ref refid="classtf_1_1Task_1a8c78c453295a553c1c016e4062da8588" kindref="member">precede</ref>(B);</highlight></codeline>
<codeline><highlight class="normal"><sp/>8:</highlight></codeline>
<codeline><highlight class="normal"><sp/>9:<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/>A.<ref refid="classtf_1_1Task_1a08ada0425b490997b6ff7f310107e5e3" kindref="member">name</ref>()<sp/><<<sp/><ref refid="cpp/io/manip/endl" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::endl</ref>;<sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/></highlight><highlight class="comment">//<sp/>TaskA</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">10:<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/>A.<ref refid="classtf_1_1Task_1a1a0afc89e8a6a416c511e74d82df135d" kindref="member">num_successors</ref>()<sp/><<<sp/><ref refid="cpp/io/manip/endl" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::endl</ref>;<sp/><sp/></highlight><highlight class="comment">//<sp/>1</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">11:<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/>A.<ref refid="classtf_1_1Task_1adefb65d68a64bd8a75364a8801cfec44" kindref="member">num_predecessors</ref>()<sp/><<<sp/><ref refid="cpp/io/manip/endl" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::endl</ref>;<sp/><sp/></highlight><highlight class="comment">//<sp/>0</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">12:<sp/></highlight></codeline>
<codeline><highlight class="normal">13:<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/>B.<ref refid="classtf_1_1Task_1a1a0afc89e8a6a416c511e74d82df135d" kindref="member">num_successors</ref>()<sp/><<<sp/><ref refid="cpp/io/manip/endl" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::endl</ref>;<sp/><sp/></highlight><highlight class="comment">//<sp/>0</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">14:<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/>B.<ref refid="classtf_1_1Task_1adefb65d68a64bd8a75364a8801cfec44" kindref="member">num_predecessors</ref>()<sp/><<<sp/><ref refid="cpp/io/manip/endl" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::endl</ref>;<sp/><sp/></highlight><highlight class="comment">//<sp/>1</highlight></codeline>
</programlisting></para>
<para>Debrief: <itemizedlist>
<listitem><para>Line 1 creates a taskflow object </para>
</listitem>
<listitem><para>Lines 2-3 create two tasks A and B </para>
</listitem>
<listitem><para>Lines 5-6 assign a name and a work to task A, and add a precedence link to task B </para>
</listitem>
<listitem><para>Line 7 adds a dependency link from A to B </para>
</listitem>
<listitem><para>Lines 9-14 dump the task attributes</para>
</listitem>
</itemizedlist>
Taskflow uses general-purpose polymorphic function wrapper, <ref refid="cpp/utility/functional/function" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::function</ref>, to store and invoke a callable in a task. You need to follow its contract to create a task. For example, the callable to construct a task must be copyable, and thus the code below won't compile:</para>
<para><programlisting filename=".cpp"><codeline><highlight class="normal">taskflow.<ref refid="classtf_1_1FlowBuilder_1a60d7a666cab71ecfa3010b2efb0d6b57" kindref="member">emplace</ref>([ptr=std::make_unique<int>(1)](){</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"captured<sp/>unique<sp/>pointer<sp/>is<sp/>not<sp/>copyable"</highlight><highlight class="normal">;</highlight></codeline>
<codeline><highlight class="normal">});</highlight></codeline>
</programlisting></para>
</sect1>
<sect1 id="StaticTasking_1VisualizeATaskDependencyGraph">
<title>Visualize a Task Dependency Graph</title><para>You can dump a taskflow to a DOT format and visualize the graph using free online tools such as <ulink url="https://dreampuf.github.io/GraphvizOnline/">GraphvizOnline</ulink> and <ulink url="http://www.webgraphviz.com/">WebGraphviz</ulink>.</para>
<para><programlisting filename=".cpp"><codeline><highlight class="normal"><sp/>1:<sp/>#include<sp/><taskflow/taskflow.hpp></highlight></codeline>
<codeline><highlight class="normal"><sp/>2:</highlight></codeline>
<codeline><highlight class="normal"><sp/>3:<sp/></highlight><highlight class="keywordtype">int</highlight><highlight class="normal"><sp/>main()<sp/>{</highlight></codeline>
<codeline><highlight class="normal"><sp/>4:<sp/></highlight></codeline>
<codeline><highlight class="normal"><sp/>5:<sp/><sp/><sp/><ref refid="classtf_1_1Taskflow" kindref="compound">tf::Taskflow</ref><sp/>taskflow;</highlight></codeline>
<codeline><highlight class="normal"><sp/>6:</highlight></codeline>
<codeline><highlight class="normal"><sp/>7:<sp/><sp/><sp/></highlight><highlight class="comment">//<sp/>create<sp/>a<sp/>task<sp/>dependency<sp/>graph</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/>8:<sp/><sp/><sp/><ref refid="classtf_1_1Task" kindref="compound">tf::Task</ref><sp/>A<sp/>=<sp/>taskflow.<ref refid="classtf_1_1FlowBuilder_1a60d7a666cab71ecfa3010b2efb0d6b57" kindref="member">emplace</ref>([]<sp/>()<sp/>{<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"Task<sp/>A\n"</highlight><highlight class="normal">;<sp/>});</highlight></codeline>
<codeline><highlight class="normal"><sp/>9:<sp/><sp/><sp/><ref refid="classtf_1_1Task" kindref="compound">tf::Task</ref><sp/>B<sp/>=<sp/>taskflow.<ref refid="classtf_1_1FlowBuilder_1a60d7a666cab71ecfa3010b2efb0d6b57" kindref="member">emplace</ref>([]<sp/>()<sp/>{<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"Task<sp/>B\n"</highlight><highlight class="normal">;<sp/>});</highlight></codeline>
<codeline><highlight class="normal">10:<sp/><sp/><sp/><ref refid="classtf_1_1Task" kindref="compound">tf::Task</ref><sp/>C<sp/>=<sp/>taskflow.<ref refid="classtf_1_1FlowBuilder_1a60d7a666cab71ecfa3010b2efb0d6b57" kindref="member">emplace</ref>([]<sp/>()<sp/>{<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"Task<sp/>C\n"</highlight><highlight class="normal">;<sp/>});</highlight></codeline>
<codeline><highlight class="normal">11:<sp/><sp/><sp/><ref refid="classtf_1_1Task" kindref="compound">tf::Task</ref><sp/>D<sp/>=<sp/>taskflow.<ref refid="classtf_1_1FlowBuilder_1a60d7a666cab71ecfa3010b2efb0d6b57" kindref="member">emplace</ref>([]<sp/>()<sp/>{<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"Task<sp/>D\n"</highlight><highlight class="normal">;<sp/>});</highlight></codeline>
<codeline><highlight class="normal">12:</highlight></codeline>
<codeline><highlight class="normal">13:<sp/><sp/><sp/></highlight><highlight class="comment">//<sp/>add<sp/>dependency<sp/>links</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">14:<sp/><sp/><sp/>A.<ref refid="classtf_1_1Task_1a8c78c453295a553c1c016e4062da8588" kindref="member">precede</ref>(B);<sp/></highlight></codeline>
<codeline><highlight class="normal">15:<sp/><sp/><sp/>A.<ref refid="classtf_1_1Task_1a8c78c453295a553c1c016e4062da8588" kindref="member">precede</ref>(C);</highlight></codeline>
<codeline><highlight class="normal">16:<sp/><sp/><sp/>B.<ref refid="classtf_1_1Task_1a8c78c453295a553c1c016e4062da8588" kindref="member">precede</ref>(D);</highlight></codeline>
<codeline><highlight class="normal">17:<sp/><sp/><sp/>C.<ref refid="classtf_1_1Task_1a8c78c453295a553c1c016e4062da8588" kindref="member">precede</ref>(D);</highlight></codeline>
<codeline><highlight class="normal">18:</highlight></codeline>
<codeline><highlight class="normal">19:<sp/><sp/><sp/>taskflow.<ref refid="classtf_1_1Taskflow_1ac433018262e44b12c4cc9f0c4748d758" kindref="member">dump</ref>(<ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref>);</highlight></codeline>
<codeline><highlight class="normal">20:<sp/>}</highlight></codeline>
</programlisting></para>
<para>Debrief: <itemizedlist>
<listitem><para>Line 5 creates a taskflow object </para>
</listitem>
<listitem><para>Lines 8-11 create four tasks </para>
</listitem>
<listitem><para>Lines 14-17 add four task dependencies </para>
</listitem>
<listitem><para>Line 19 dumps the taskflow in the DOT format through standard output</para>
</listitem>
</itemizedlist>
<dotfile name="simple.dot"></dotfile>
</para>
</sect1>
<sect1 id="StaticTasking_1ModifyTaskAttributes">
<title>Modify Task Attributes</title><para>This example demonstrates how to modify a task's attributes using methods defined in the task handler.</para>
<para><programlisting filename=".cpp"><codeline><highlight class="normal"><sp/>1:<sp/>#include<sp/><taskflow/taskflow.hpp></highlight></codeline>
<codeline><highlight class="normal"><sp/>2:</highlight></codeline>
<codeline><highlight class="normal"><sp/>3:<sp/></highlight><highlight class="keywordtype">int</highlight><highlight class="normal"><sp/>main()<sp/>{</highlight></codeline>
<codeline><highlight class="normal"><sp/>4:</highlight></codeline>
<codeline><highlight class="normal"><sp/>5:<sp/><sp/><sp/><ref refid="classtf_1_1Taskflow" kindref="compound">tf::Taskflow</ref><sp/>taskflow;</highlight></codeline>
<codeline><highlight class="normal"><sp/>6:</highlight></codeline>
<codeline><highlight class="normal"><sp/>7:<sp/><sp/><sp/><ref refid="cpp/container/vector" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::vector<tf::Task></ref><sp/>tasks<sp/>=<sp/>{<sp/></highlight></codeline>
<codeline><highlight class="normal"><sp/>8:<sp/><sp/><sp/><sp/><sp/>taskflow.<ref refid="classtf_1_1FlowBuilder_1acab0b4ac82260f47fdb36a3244ee3aaf" kindref="member">placeholder</ref>(),<sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/></highlight><highlight class="comment">//<sp/>create<sp/>a<sp/>task<sp/>with<sp/>no<sp/>work</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><sp/>9:<sp/><sp/><sp/><sp/><sp/>taskflow.<ref refid="classtf_1_1FlowBuilder_1acab0b4ac82260f47fdb36a3244ee3aaf" kindref="member">placeholder</ref>()<sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/></highlight><highlight class="comment">//<sp/>create<sp/>a<sp/>task<sp/>with<sp/>no<sp/>work</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">10:<sp/><sp/><sp/>};</highlight></codeline>
<codeline><highlight class="normal">11:</highlight></codeline>
<codeline><highlight class="normal">12:<sp/><sp/><sp/>tasks[0].name(</highlight><highlight class="stringliteral">"This<sp/>is<sp/>Task<sp/>0"</highlight><highlight class="normal">);</highlight></codeline>
<codeline><highlight class="normal">13:<sp/><sp/><sp/>tasks[1].name(</highlight><highlight class="stringliteral">"This<sp/>is<sp/>Task<sp/>1"</highlight><highlight class="normal">);</highlight></codeline>
<codeline><highlight class="normal">14:<sp/><sp/><sp/>tasks[0].precede(tasks[1]);</highlight></codeline>
<codeline><highlight class="normal">15:</highlight></codeline>
<codeline><highlight class="normal">16:<sp/><sp/><sp/></highlight><highlight class="keywordflow">for</highlight><highlight class="normal">(</highlight><highlight class="keyword">auto</highlight><highlight class="normal"><sp/>task<sp/>:<sp/>tasks)<sp/>{<sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/></highlight><highlight class="comment">//<sp/>print<sp/>out<sp/>each<sp/>task's<sp/>attributes</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">17:<sp/><sp/><sp/><sp/><sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/>task.name()<sp/><<<sp/></highlight><highlight class="stringliteral">":<sp/>"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">18:<sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><<<sp/></highlight><highlight class="stringliteral">"num_predecessors="</highlight><highlight class="normal"><sp/><<<sp/>task.num_predecessors()<sp/><<<sp/></highlight><highlight class="stringliteral">",<sp/>"</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">19:<sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><<<sp/></highlight><highlight class="stringliteral">"num_successors="</highlight><highlight class="normal"><sp/><<<sp/>task.num_successors()<sp/><<<sp/></highlight><highlight class="charliteral">'\n'</highlight><highlight class="normal">;</highlight></codeline>
<codeline><highlight class="normal">20:<sp/><sp/><sp/>}</highlight></codeline>
<codeline><highlight class="normal">21:</highlight></codeline>
<codeline><highlight class="normal">22:<sp/><sp/><sp/>taskflow.<ref refid="classtf_1_1Taskflow_1ac433018262e44b12c4cc9f0c4748d758" kindref="member">dump</ref>(<ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref>);<sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/></highlight><highlight class="comment">//<sp/>dump<sp/>the<sp/>taskflow<sp/>graph</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">23:</highlight></codeline>
<codeline><highlight class="normal">24:<sp/><sp/><sp/>tasks[0].work([](){<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"got<sp/>a<sp/>new<sp/>work!\n"</highlight><highlight class="normal">;<sp/>});</highlight></codeline>
<codeline><highlight class="normal">25:<sp/><sp/><sp/>tasks[1].work([](){<sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"got<sp/>a<sp/>new<sp/>work!\n"</highlight><highlight class="normal">;<sp/>});</highlight></codeline>
<codeline><highlight class="normal">26:</highlight></codeline>
<codeline><highlight class="normal">27:<sp/><sp/><sp/></highlight><highlight class="keywordflow">return</highlight><highlight class="normal"><sp/>0;</highlight></codeline>
<codeline><highlight class="normal">28:<sp/>}</highlight></codeline>
</programlisting></para>
<para>The output of this program looks like the following:</para>
<para><programlisting filename=".sh"><codeline><highlight class="normal">This<sp/>is<sp/>Task<sp/>0:<sp/>num_predecessors=0,<sp/>num_successors=1</highlight></codeline>
<codeline><highlight class="normal">This<sp/>is<sp/>Task<sp/>1:<sp/>num_predecessors=1,<sp/>num_successors=0</highlight></codeline>
<codeline><highlight class="normal">digraph<sp/>Taskflow<sp/>{</highlight></codeline>
<codeline><highlight class="normal">"This<sp/>is<sp/>Task<sp/>1";</highlight></codeline>
<codeline><highlight class="normal">"This<sp/>is<sp/>Task<sp/>0";</highlight></codeline>
<codeline><highlight class="normal">"This<sp/>is<sp/>Task<sp/>0"<sp/>-><sp/>"This<sp/>is<sp/>Task<sp/>1";</highlight></codeline>
<codeline><highlight class="normal">}</highlight></codeline>
</programlisting></para>
<para>Debrief: <itemizedlist>
<listitem><para>Line 5 creates a taskflow object </para>
</listitem>
<listitem><para>Lines 7-10 create two placeholder tasks with no works and stores the corresponding task handles in a vector </para>
</listitem>
<listitem><para>Lines 12-13 name the two tasks with human-readable strings </para>
</listitem>
<listitem><para>Line 14 adds a dependency link from the first task to the second task </para>
</listitem>
<listitem><para>Lines 16-20 print out the name of each task, the number of predecessors, and the number of successors </para>
</listitem>
<listitem><para>Line 22 dumps the task dependency graph to a <ulink url="https://dreampuf.github.io/GraphvizOnline/">GraphViz Online</ulink> format (dot) </para>
</listitem>
<listitem><para>Lines 24-25 assign a new target to each task</para>
</listitem>
</itemizedlist>
You can change the name and work of a task at anytime before running the graph. The later assignment overwrites the previous values.</para>
</sect1>
<sect1 id="StaticTasking_1TraverseAdjacentTasks">
<title>Traverse Adjacent Tasks</title><para>You can iterate the successor list and the predecessor list of a task by using <ref refid="classtf_1_1Task_1aff13a503d4a3c994eb08cb6f22e1b427" kindref="member">tf::Task::for_each_successor</ref> and <ref refid="classtf_1_1Task_1a31d8069d4c0b10b55e68d260c4d28c1f" kindref="member">tf::Task::for_each_predecessor</ref>, respectively. Each method takes a lambda and applies it to a successor or a predecessor being traversed.</para>
<para><programlisting filename=".cpp"><codeline><highlight class="comment">//<sp/>traverse<sp/>all<sp/>successors<sp/>of<sp/>my_task</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">my_task.for_each_successor([s=0]<sp/>(<ref refid="classtf_1_1Task" kindref="compound">tf::Task</ref><sp/>successor)<sp/></highlight><highlight class="keyword">mutable</highlight><highlight class="normal"><sp/>{</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"successor<sp/>"</highlight><highlight class="normal"><sp/><<<sp/>s++<sp/><<<sp/></highlight><highlight class="charliteral">'\n'</highlight><highlight class="normal">;</highlight></codeline>
<codeline><highlight class="normal">});</highlight></codeline>
<codeline><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"></highlight><highlight class="comment">//<sp/>traverse<sp/>all<sp/>predecessors<sp/>of<sp/>my_task</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">my_task.for_each_predecessor([d=0]<sp/>(<ref refid="classtf_1_1Task" kindref="compound">tf::Task</ref><sp/>predecessor)<sp/></highlight><highlight class="keyword">mutable</highlight><highlight class="normal"><sp/>{</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"predecessor<sp/>"</highlight><highlight class="normal"><sp/><<<sp/>d++<sp/><<<sp/></highlight><highlight class="charliteral">'\n'</highlight><highlight class="normal">;</highlight></codeline>
<codeline><highlight class="normal">});</highlight></codeline>
</programlisting></para>
<para>If the task contains a subflow, you can use <ref refid="classtf_1_1Task_1a20a23c08612084e96bda764e06842c3a" kindref="member">tf::Task::for_each_subflow_task</ref> to iterate all tasks associated with that subflow.</para>
<para><programlisting filename=".cpp"><codeline><highlight class="normal">my_task.for_each_subflow_task([](<ref refid="classtf_1_1Task" kindref="compound">tf::Task</ref><sp/>stask){</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"subflow<sp/>task<sp/>"</highlight><highlight class="normal"><sp/><<<sp/>stask.<ref refid="classtf_1_1Task_1a08ada0425b490997b6ff7f310107e5e3" kindref="member">name</ref>()<sp/><<<sp/></highlight><highlight class="charliteral">'\n'</highlight><highlight class="normal">;</highlight></codeline>
<codeline><highlight class="normal">});</highlight></codeline>
</programlisting></para>
</sect1>
<sect1 id="StaticTasking_1AttachUserDataToATask">
<title>Attach User Data to a Task</title><para>You can attach custom data to a task using <ref refid="classtf_1_1Task_1afd82ab6d6518d1142a72c4d2c97ff114" kindref="member">tf::Task::data(void*)</ref> and access it using <ref refid="classtf_1_1Task_1a320827cb70295a6fe2cc37691405409c" kindref="member">tf::Task::data()</ref>. Each node in a taskflow is associated with a C-styled data pointer (i.e., <computeroutput>void*</computeroutput>) you can use to point to user data and access it in the body of a task callable. The following example attaches an integer to a task and accesses that integer through capturing the data in the callable.</para>
<para><programlisting filename=".cpp"><codeline><highlight class="keywordtype">int</highlight><highlight class="normal"><sp/>my_data<sp/>=<sp/>5;</highlight></codeline>
<codeline><highlight class="normal"><ref refid="classtf_1_1Task" kindref="compound">tf::Task</ref><sp/>task<sp/>=<sp/>taskflow.<ref refid="classtf_1_1FlowBuilder_1acab0b4ac82260f47fdb36a3244ee3aaf" kindref="member">placeholder</ref>();</highlight></codeline>
<codeline><highlight class="normal">task.<ref refid="classtf_1_1Task_1afd82ab6d6518d1142a72c4d2c97ff114" kindref="member">data</ref>(&my_data)</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/>.<ref refid="classtf_1_1Task_1a2f6f4cec42d016e5eb89390f362ffe99" kindref="member">work</ref>([task](){</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/></highlight><highlight class="keywordtype">int</highlight><highlight class="normal"><sp/>my_date<sp/>=<sp/>*</highlight><highlight class="keyword">static_cast<</highlight><highlight class="keywordtype">int</highlight><highlight class="normal">*</highlight><highlight class="keyword">></highlight><highlight class="normal">(task.<ref refid="classtf_1_1Task_1afd82ab6d6518d1142a72c4d2c97ff114" kindref="member">data</ref>());</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/><<<sp/></highlight><highlight class="stringliteral">"my_data:<sp/>"</highlight><highlight class="normal"><sp/><<<sp/>my_data;<sp/></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/>});</highlight></codeline>
</programlisting></para>
<para>Notice that you need to create a placeholder task first before assigning it a work callable. Only this way can you capture that task in the lambda and access its attached data in the lambda body.</para>
<para><simplesect kind="attention"><para>It is your responsibility to ensure that the attached data stay alive during the execution of its task.</para>
</simplesect>
</para>
</sect1>
<sect1 id="StaticTasking_1UnderstandTheLifetimeOfATask">
<title>Understand the Lifetime of a Task</title><para>A task lives with its graph and belongs to only a graph at a time, and is not destroyed until the graph gets cleaned up. The lifetime of a task refers to the user-given callable object, including captured values. As long as the graph is alive, all the associated tasks exist.</para>
<para><simplesect kind="attention"><para>It is your responsibility to keep tasks and graph alive during their execution.</para>
</simplesect>
</para>
</sect1>
<sect1 id="StaticTasking_1MoveATaskflow">
<title>Move a Taskflow</title><para>You can construct or assign a taskflow from a <emphasis>moved</emphasis> taskflow. Moving a taskflow to another will result in transferring the underlying graph data structures from one to the other.</para>
<para><programlisting filename=".cpp"><codeline><highlight class="normal"><ref refid="classtf_1_1Taskflow" kindref="compound">tf::Taskflow</ref><sp/>taskflow1,<sp/>taskflow3;</highlight></codeline>
<codeline><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">taskflow1.<ref refid="classtf_1_1FlowBuilder_1a60d7a666cab71ecfa3010b2efb0d6b57" kindref="member">emplace</ref>([](){});</highlight></codeline>
<codeline><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"></highlight><highlight class="comment">//<sp/>move-construct<sp/>taskflow2<sp/>from<sp/>taskflow1</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"><ref refid="classtf_1_1Taskflow" kindref="compound">tf::Taskflow</ref><sp/>taskflow2(<ref refid="cpp/utility/move" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::move</ref>(taskflow1));</highlight></codeline>
<codeline><highlight class="normal">assert(taskflow2.num_tasks()<sp/>==<sp/>1<sp/>&&<sp/>taskflow1.<ref refid="classtf_1_1Taskflow_1af4f03bca084deb5c2228ac8936d33649" kindref="member">num_tasks</ref>()<sp/>==<sp/>0);</highlight></codeline>
<codeline><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal"></highlight><highlight class="comment">//<sp/>move-assign<sp/>taskflow3<sp/>to<sp/>taskflow2</highlight><highlight class="normal"></highlight></codeline>
<codeline><highlight class="normal">taskflow3<sp/>=<sp/><ref refid="cpp/utility/move" kindref="compound" external="/Users/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::move</ref>(taskflow2);</highlight></codeline>
<codeline><highlight class="normal">assert(taskflow3.<ref refid="classtf_1_1Taskflow_1af4f03bca084deb5c2228ac8936d33649" kindref="member">num_tasks</ref>()<sp/>==<sp/>1<sp/>&&<sp/>taskflow2.num_tasks()<sp/>==<sp/>0);</highlight></codeline>
</programlisting></para>
<para>You can only move a taskflow to another while that taskflow is not being run by an executor. Moving a running taskflow can result in undefined behavior. Please see <ref refid="ExecuteTaskflow_1ExecuteATaskflowWithTransferredOwnership" kindref="member">Execute a Taskflow with Transferred Ownership</ref> for more details. </para>
</sect1>
</detaileddescription>
<location file="doxygen/cookbook/static_tasking.dox"/>
</compounddef>
</doxygen>