-
-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Expand file tree
/
Copy pathConditionalTasking.html
More file actions
506 lines (504 loc) · 54.8 KB
/
Copy pathConditionalTasking.html
File metadata and controls
506 lines (504 loc) · 54.8 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
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
<!-- HTML header for doxygen 1.13.1-->
<!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.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Taskflow: A General-purpose Task-parallel Programming System: Conditional Tasking</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="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<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.css" rel="stylesheet" type="text/css" />
<link href="custom.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectlogo"><img alt="Logo" src="taskflow_logo.png"/></td>
<td id="projectalign">
<div id="projectname"><a href="https://github.com/taskflow/taskflow" style="color:inherit; text-decoration:none;">Taskflow: A General-purpose Task-parallel Programming System</a>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.13.1 -->
<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',true);
$(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function(){initNavTree('ConditionalTasking.html',''); initResizable(true); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">Conditional Tasking</div></div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul>
<li class="level1">
<a href="#CreateAConditionTask">Create a Condition Task</a>
</li>
<li class="level1">
<a href="#TaskSchedulingPolicy">Understand our Task-level Scheduling</a>
<ul>
<li class="level2">
<a href="#TaskLevelSchedulingExample">Example</a>
</li>
</ul>
</li>
<li class="level1">
<a href="#AvoidCommonPitfalls">Avoid Common Pitfalls</a>
<ul>
<li class="level2">
<a href="#PitfallNoSourceTask">Pitfall 1: No Source Task</a>
</li>
<li class="level2">
<a href="#PitfallTaskRace">Pitfall 2: Task Race</a>
</li>
<li class="level2">
<a href="#PitfallDeadlock">Pitfall 3: Deadlock from Strong Back-edge</a>
</li>
</ul>
</li>
<li class="level1">
<a href="#ImplementControlFlowGraphs">Implement Control-flow Graphs</a>
<ul>
<li class="level2">
<a href="#ImplementIfElseControlFlow">Implement If-Else Control Flow</a>
</li>
<li class="level2">
<a href="#ImplementSwitchControlFlow">Implement Switch Control Flow</a>
</li>
<li class="level2">
<a href="#ImplementDoWhileLoopControlFlow">Implement Do-While-Loop Control Flow</a>
</li>
<li class="level2">
<a href="#ImplementWhileLoopControlFlow">Implement While-Loop Control Flow</a>
</li>
</ul>
</li>
<li class="level1">
<a href="#CreateAMultiConditionTask">Create a Multi-condition Task</a>
</li>
</ul>
</div>
<div class="textblock"><p>One of the most powerful features that distinguishes Taskflow from other systems is its support for <em>conditional tasking</em>, also known as the <em>control taskflow programming model</em> (CTFG). CTFG allows you to embed control flow directly within a taskflow graph, enabling tasks to make decisions dynamically during execution. This mechanism supports advanced in-graph control flow patterns, such as dynamic branching, loops, and conditionals—that are typically difficult or impossible to express in traditional task graph models.</p>
<h1><a class="anchor" id="CreateAConditionTask"></a>
Create a Condition Task</h1>
<p>A condition task returns an integer index indicating which successor task to execute next. The index corresponds to the position of the successor in the order it was added during task construction. The following example creates an if-else block using a condition task.</p>
<div class="fragment"><div class="line"><a class="code hl_class" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div>
<div class="line"><span class="keyword">auto</span> [init, cond, yes, no] = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>(</div>
<div class="line"> [] () { },</div>
<div class="line"> [] () { <span class="keywordflow">return</span> 0; },</div>
<div class="line"> [] () { std::cout << <span class="stringliteral">"yes\n"</span>; },</div>
<div class="line"> [] () { std::cout << <span class="stringliteral">"no\n"</span>; }</div>
<div class="line">);</div>
<div class="line">cond.<a class="code hl_function" href="classtf_1_1Task.html#a331b1b726555072e7c7d10941257f664">succeed</a>(init)</div>
<div class="line"> .<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(yes, no); <span class="comment">// executes yes if cond returns 0</span></div>
<div class="line"> <span class="comment">// executes no if cond returns 1</span></div>
<div class="ttc" id="aclasstf_1_1FlowBuilder_html_a4d52a7fe2814b264846a2085e931652c"><div class="ttname"><a href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">tf::FlowBuilder::emplace</a></div><div class="ttdeci">Task emplace(C &&callable)</div><div class="ttdoc">creates a static task</div><div class="ttdef"><b>Definition</b> flow_builder.hpp:1571</div></div>
<div class="ttc" id="aclasstf_1_1Task_html_a331b1b726555072e7c7d10941257f664"><div class="ttname"><a href="classtf_1_1Task.html#a331b1b726555072e7c7d10941257f664">tf::Task::succeed</a></div><div class="ttdeci">Task & succeed(Ts &&... tasks)</div><div class="ttdoc">adds precedence links from other tasks to this</div><div class="ttdef"><b>Definition</b> task.hpp:1266</div></div>
<div class="ttc" id="aclasstf_1_1Task_html_a8c78c453295a553c1c016e4062da8588"><div class="ttname"><a href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">tf::Task::precede</a></div><div class="ttdeci">Task & precede(Ts &&... tasks)</div><div class="ttdoc">adds precedence links from this to other tasks</div><div class="ttdef"><b>Definition</b> task.hpp:1258</div></div>
<div class="ttc" id="aclasstf_1_1Taskflow_html"><div class="ttname"><a href="classtf_1_1Taskflow.html">tf::Taskflow</a></div><div class="ttdoc">class to create a taskflow object</div><div class="ttdef"><b>Definition</b> taskflow.hpp:64</div></div>
</div><!-- fragment --><div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_conditional-tasking-if-else.svg" width="370" height="131"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>The condition task <code>cond</code> is connected to two successor tasks, <code>yes</code> and <code>no</code>, via <code>precede(yes, no)</code>. When <code>cond</code> returns <code>0</code>, the execution moves on to <code>yes</code>. When <code>cond</code> returns <code>1</code>, the execution moves on to <code>no</code>.</p>
<dl class="section note"><dt>Note</dt><dd>It is your responsibility to ensure that the return value of a condition task corresponds to a valid successor. If the returned index is out of range, the executor will not schedule any successor tasks.</dd></dl>
<p>A condition task can form a cycle to express <em>iterative</em> control flow. The example below demonstrates a simple yet commonly used feedback loop implemented using a condition task that returns a random binary value. If the return value from <code>cond</code> is <code>0</code>, the task loops back to itself; otherwise, it proceeds to <code>stop</code>.</p>
<div class="fragment"><div class="line"><a class="code hl_class" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div>
<div class="line"> </div>
<div class="line"><a class="code hl_class" href="classtf_1_1Task.html">tf::Task</a> init = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"init"</span>);</div>
<div class="line"><a class="code hl_class" href="classtf_1_1Task.html">tf::Task</a> stop = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"stop"</span>);</div>
<div class="line"><span class="comment">// creates a condition task that returns 0 or 1</span></div>
<div class="line"><a class="code hl_class" href="classtf_1_1Task.html">tf::Task</a> cond = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){</div>
<div class="line"> std::cout << <span class="stringliteral">"flipping a coin\n"</span>;</div>
<div class="line"> <span class="keywordflow">return</span> std::rand() % 2;</div>
<div class="line">}).name(<span class="stringliteral">"cond"</span>);</div>
<div class="line"><span class="comment">// creates a feedback loop {0: cond, 1: stop}</span></div>
<div class="line">init.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(cond);</div>
<div class="line">cond.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(cond, stop); <span class="comment">// returns 0 to 'cond' or 1 to 'stop'</span></div>
<div class="line">executor.run(taskflow).wait();</div>
<div class="ttc" id="aclasstf_1_1Task_html"><div class="ttname"><a href="classtf_1_1Task.html">tf::Task</a></div><div class="ttdoc">class to create a task handle over a taskflow node</div><div class="ttdef"><b>Definition</b> task.hpp:569</div></div>
</div><!-- fragment --><div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_conditional-tasking-1.svg" width="370" height="106"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>Creating a taskflow with complex control flow often requires only a few lines of code to implement. Different control flow paths can execute in parallel, making it easy to express both logic and concurrency. The code below creates a taskflow with three condition tasks to demonstrate this capability:</p>
<div class="fragment"><div class="line"><a class="code hl_class" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div>
<div class="line"> </div>
<div class="line"><a class="code hl_class" href="classtf_1_1Task.html">tf::Task</a> A = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"A"</span>);</div>
<div class="line"><a class="code hl_class" href="classtf_1_1Task.html">tf::Task</a> B = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"B"</span>);</div>
<div class="line"><a class="code hl_class" href="classtf_1_1Task.html">tf::Task</a> C = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"C"</span>);</div>
<div class="line">tf::Task D = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"D"</span>);</div>
<div class="line">tf::Task E = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"E"</span>);</div>
<div class="line">tf::Task F = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"F"</span>);</div>
<div class="line">tf::Task G = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"G"</span>);</div>
<div class="line">tf::Task H = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"H"</span>);</div>
<div class="line">tf::Task I = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"I"</span>);</div>
<div class="line">tf::Task K = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"K"</span>);</div>
<div class="line">tf::Task L = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"L"</span>);</div>
<div class="line">tf::Task M = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){}).name(<span class="stringliteral">"M"</span>);</div>
<div class="line">tf::Task cond_1 = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){ <span class="keywordflow">return</span> std::rand()%2; }).name(<span class="stringliteral">"cond_1"</span>);</div>
<div class="line">tf::Task cond_2 = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){ <span class="keywordflow">return</span> std::rand()%2; }).name(<span class="stringliteral">"cond_2"</span>);</div>
<div class="line">tf::Task cond_3 = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){ <span class="keywordflow">return</span> std::rand()%2; }).name(<span class="stringliteral">"cond_3"</span>);</div>
<div class="line"> </div>
<div class="line">A.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(B, F);</div>
<div class="line">B.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(C);</div>
<div class="line">C.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(D);</div>
<div class="line">D.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(cond_1);</div>
<div class="line">E.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(K);</div>
<div class="line">F.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(cond_2);</div>
<div class="line">H.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(I);</div>
<div class="line">I.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(cond_3);</div>
<div class="line">L.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(M);</div>
<div class="line"> </div>
<div class="line">cond_1.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(B, E); <span class="comment">// return 0 to 'B' or 1 to 'E'</span></div>
<div class="line">cond_2.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(G, H); <span class="comment">// return 0 to 'G' or 1 to 'H'</span></div>
<div class="line">cond_3.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(cond_3, L); <span class="comment">// return 0 to 'cond_3' or 1 to 'L'</span></div>
<div class="line"> </div>
<div class="line">taskflow.<a class="code hl_function" href="classtf_1_1Taskflow.html#ac433018262e44b12c4cc9f0c4748d758">dump</a>(std::cout);</div>
<div class="ttc" id="aclasstf_1_1Taskflow_html_ac433018262e44b12c4cc9f0c4748d758"><div class="ttname"><a href="classtf_1_1Taskflow.html#ac433018262e44b12c4cc9f0c4748d758">tf::Taskflow::dump</a></div><div class="ttdeci">void dump(std::ostream &ostream) const</div><div class="ttdoc">dumps the taskflow to a DOT format through a std::ostream target</div><div class="ttdef"><b>Definition</b> taskflow.hpp:433</div></div>
</div><!-- fragment --><p>The above code creates three condition tasks to implement three different control-flow tasks:</p><ol type="1">
<li>A condition task <code>cond_1</code> that loops back to <code>B</code> on returning <code>0</code>, or proceeds to <code>E</code> on returning <code>1</code>,</li>
<li>A condition task <code>cond_2</code> that goes to <code>G</code> on returning <code>0</code>, or <code>H</code> on returning <code>1</code>,</li>
<li>A condition task <code>cond_3</code> that loops back to itself on returning <code>0</code>, or proceeds to <code>L</code> on returning <code>1</code> </li>
</ol>
<div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_conditional-tasking-2.svg" width="1170" height="259"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>In this particular example, we can clearly see the advantage of CTFG: the execution of <code>cond_1</code> can overlap with <code>cond_2</code> or <code>cond_3</code>, enabling greater concurrency in control-driven workloads. Unlike traditional task graph models that require static structure or external orchestration to handle control flow, CTFG allows tasks to make decisions dynamically and continue execution without global synchronization barriers. This design leads to better parallelism, reduced overhead, and more expressive task graphs, especially in workloads with branching or iterative control flows.</p>
<h1><a class="anchor" id="TaskSchedulingPolicy"></a>
Understand our Task-level Scheduling</h1>
<p>In order to understand how an executor schedules condition tasks, we define two dependency types, <em>strong dependency</em> and <em>weak dependency</em>. A strong dependency is a preceding link from one non-condition task to another task. A weak dependency is a preceding link from one condition task to another task. The number of dependencies of a task is the sum of its strong dependencies and weak dependencies. The table below lists the number of strong dependencies and weak dependencies of each task in the previous example:</p>
<div align="center"> <table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadCenter">task </th><th class="markdownTableHeadCenter">strong dependency </th><th class="markdownTableHeadCenter">weak dependency </th><th class="markdownTableHeadNone">dependencies </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyCenter">A </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyNone">0 </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyCenter">B </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyNone">2 </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyCenter">C </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyNone">1 </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyCenter">D </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyNone">1 </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyCenter">E </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyNone">1 </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyCenter">F </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyNone">1 </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyCenter">G </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyNone">1 </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyCenter">H </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyNone">1 </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyCenter">I </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyNone">1 </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyCenter">K </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyNone">1 </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyCenter">L </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyNone">1 </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyCenter">M </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyNone">1 </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyCenter">cond_1 </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyNone">1 </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyCenter">cond_2 </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyCenter">0 </td><td class="markdownTableBodyNone">1 </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyCenter">cond_3 </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyCenter">1 </td><td class="markdownTableBodyNone">2 </td></tr>
</table>
</div><p>You can query the number of strong dependencies, the number of weak dependencies, and the number of dependencies of a task.</p>
<div class="fragment"><div class="line"><a class="code hl_class" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div>
<div class="line"> </div>
<div class="line"><a class="code hl_class" href="classtf_1_1Task.html">tf::Task</a> task = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){});</div>
<div class="line"> </div>
<div class="line"><span class="comment">// ... add more tasks and preceding links</span></div>
<div class="line">std::cout << task.<a class="code hl_function" href="classtf_1_1Task.html#adefb65d68a64bd8a75364a8801cfec44">num_predecessors</a>() << <span class="charliteral">'\n'</span>;</div>
<div class="line">std::cout << task.<a class="code hl_function" href="classtf_1_1Task.html#a0b7b789c9b8a21927a992f6ccc11de81">num_strong_dependencies</a>() << <span class="charliteral">'\n'</span>; </div>
<div class="line">std::cout << task.<a class="code hl_function" href="classtf_1_1Task.html#ad5e874b7cc77df1e7dc875d436ff7b72">num_weak_dependencies</a>() << <span class="charliteral">'\n'</span>;</div>
<div class="ttc" id="aclasstf_1_1Task_html_a0b7b789c9b8a21927a992f6ccc11de81"><div class="ttname"><a href="classtf_1_1Task.html#a0b7b789c9b8a21927a992f6ccc11de81">tf::Task::num_strong_dependencies</a></div><div class="ttdeci">size_t num_strong_dependencies() const</div><div class="ttdoc">queries the number of strong dependencies of the task</div><div class="ttdef"><b>Definition</b> task.hpp:1398</div></div>
<div class="ttc" id="aclasstf_1_1Task_html_ad5e874b7cc77df1e7dc875d436ff7b72"><div class="ttname"><a href="classtf_1_1Task.html#ad5e874b7cc77df1e7dc875d436ff7b72">tf::Task::num_weak_dependencies</a></div><div class="ttdeci">size_t num_weak_dependencies() const</div><div class="ttdoc">queries the number of weak dependencies of the task</div><div class="ttdef"><b>Definition</b> task.hpp:1403</div></div>
<div class="ttc" id="aclasstf_1_1Task_html_adefb65d68a64bd8a75364a8801cfec44"><div class="ttname"><a href="classtf_1_1Task.html#adefb65d68a64bd8a75364a8801cfec44">tf::Task::num_predecessors</a></div><div class="ttdeci">size_t num_predecessors() const</div><div class="ttdoc">queries the number of predecessors of the task</div><div class="ttdef"><b>Definition</b> task.hpp:1393</div></div>
</div><!-- fragment --><p>When you submit a task to an executor, the scheduler starts with tasks of <em>zero dependencies</em> (both zero strong and weak dependencies) and continues to execute successive tasks whenever their <em>strong dependencies</em> are met. However, the scheduler skips this rule when executing a condition task and jumps directly to its successors indexed by the return value.</p>
<div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_task_level_scheduling.svg" width="1059" height="470"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>Each task has an <em>atomic</em> join counter to keep track of strong dependencies that are met at runtime. When a task completes, the join counter is restored to the task's strong dependency number in the graph, such that the subsequent execution can reuse the counter again.</p>
<h2><a class="anchor" id="TaskLevelSchedulingExample"></a>
Example</h2>
<p>Let's take a look at an example to understand how task-level scheduling works. Suppose we have the following taskflow of one condition task <code>cond</code> that forms a loop to itself on returning <code>0</code> and moves on to <code>stop</code> on returning <code>1</code>:</p>
<div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_conditional-tasking-1.svg" width="370" height="106"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>The scheduler starts with <code>init</code> task because it has no dependencies (both strong and weak dependencies). Then, the scheduler moves on to the condition task <code>cond</code>. If <code>cond</code> returns <code>0</code>, the scheduler enqueues <code>cond</code> and runs it again. If <code>cond</code> returns <code>1</code>, the scheduler enqueues <code>stop</code> and then moves on.</p>
<h1><a class="anchor" id="AvoidCommonPitfalls"></a>
Avoid Common Pitfalls</h1>
<p>Condition tasks are powerful but require careful graph construction. The following pitfalls are the most common sources of bugs when using conditional tasking, ranging from silent deadlocks to non-deterministic task races.</p>
<h2><a class="anchor" id="PitfallNoSourceTask"></a>
Pitfall 1: No Source Task</h2>
<p>Every taskflow must have at least one task with zero dependencies for the scheduler to start with. When a condition task forms a cycle, it is easy to accidentally create a graph where every task has at least one incoming edge, leaving the scheduler with no entry point.</p>
<p>The figure below shows common pitfalls and their remedies.</p>
<div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_conditional-tasking-pitfalls.svg" width="1232" height="371"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>In the <code>error1</code> scenario, there is no source task for the scheduler to start with. The simplest fix is to add a task <code>S</code> with no dependencies that precedes the rest of the graph, giving the scheduler an unambiguous entry point.</p>
<h2><a class="anchor" id="PitfallTaskRace"></a>
Pitfall 2: Task Race</h2>
<p>A task race occurs when the same task can be scheduled more than once simultaneously through different paths. This typically happens when a task has both a strong dependency from a regular task and a weak dependency from a condition task.</p>
<p>In the <code>error2</code> scenario, task <code>D</code> can be scheduled twice: once by <code>E</code> through its strong dependency, and once by <code>C</code> through its weak dependency (when <code>C</code> returns <code>1</code>). If both paths activate <code>D</code> at the same time, <code>D</code> runs concurrently with itself, which is undefined behavior. The fix is to insert an auxiliary task <code>D-aux</code> between the two paths so that <code>D</code> always has exactly one active predecessor at a time.</p>
<p>In the risky scenario, task <code>X</code> may be raced by <code>M</code> and <code>P</code> if <code>M</code> returns <code>0</code> and <code>P</code> returns <code>1</code> simultaneously, triggering <code>X</code> from two different condition tasks at once. Whenever a task sits at the junction of multiple condition task outputs, carefully check whether those condition tasks can fire concurrently.</p>
<h2><a class="anchor" id="PitfallDeadlock"></a>
Pitfall 3: Deadlock from Strong Back-edge</h2>
<p>A deadlock occurs when a condition task loops back to a task via a strong dependency rather than a weak one. Because the scheduler only moves a task to the ready queue when all its <em>strong</em> dependencies are satisfied, a loop that creates a strong back-edge will permanently block: the loop body waits for the condition task to complete, but the condition task can never re-run because the loop body has not been executed yet.</p>
<p>The wrong while-loop implementation at <a class="el" href="#ImplementWhileLoopControlFlow">Implement While-Loop Control Flow</a> is a concrete example of this pitfall. When the body task <code>i++</code> directly precedes the loop condition task <code>cond</code> with <code>body.precede(cond)</code>, it creates a strong dependency. After <code>init</code> runs and decrements <code>cond's</code> strong dependency count by one, <code>cond</code> still waits for <code>i++</code> to complete before it can run. But <code>i++</code> only runs after <code>cond</code> returns <code>0</code>, so neither task can proceed and the graph deadlocks. The correct fix is to introduce a dedicated back-edge condition task <code>back</code> that returns <code>0</code> unconditionally to <code>cond</code>, creating a weak dependency instead.</p>
<dl class="section note"><dt>Note</dt><dd>When in doubt, use <a class="el" href="classtf_1_1Taskflow.html#ac433018262e44b12c4cc9f0c4748d758" title="dumps the taskflow to a DOT format through a std::ostream target">tf::Taskflow::dump</a> to visualize your graph and cross-reference the strong and weak dependency counts in the table at <a class="el" href="#TaskSchedulingPolicy">Understand our Task-level Scheduling</a>. A task that has both strong and weak incoming edges from active paths is a strong signal that a race or deadlock may be present.</dd></dl>
<h1><a class="anchor" id="ImplementControlFlowGraphs"></a>
Implement Control-flow Graphs</h1>
<h2><a class="anchor" id="ImplementIfElseControlFlow"></a>
Implement If-Else Control Flow</h2>
<p>You can use conditional tasking to implement if-else control flow. The following example creates a nested if-else control flow diagram that executes three condition tasks to check the range of <code>i</code>.</p>
<div class="fragment"><div class="line"><a class="code hl_class" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">int</span> i;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// create three condition tasks for nested control flow</span></div>
<div class="line"><span class="keyword">auto</span> initi = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([&](){ i=3; }); </div>
<div class="line"><span class="keyword">auto</span> cond1 = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([&](){ <span class="keywordflow">return</span> i>1 ? 1 : 0; }); </div>
<div class="line"><span class="keyword">auto</span> cond2 = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([&](){ <span class="keywordflow">return</span> i>2 ? 1 : 0; }); </div>
<div class="line"><span class="keyword">auto</span> cond3 = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([&](){ <span class="keywordflow">return</span> i>3 ? 1 : 0; }); </div>
<div class="line"><span class="keyword">auto</span> equl1 = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([&](){ std::cout << <span class="stringliteral">"i=1\n"</span>; }); </div>
<div class="line"><span class="keyword">auto</span> equl2 = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([&](){ std::cout << <span class="stringliteral">"i=2\n"</span>; }); </div>
<div class="line"><span class="keyword">auto</span> equl3 = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([&](){ std::cout << <span class="stringliteral">"i=3\n"</span>; }); </div>
<div class="line"><span class="keyword">auto</span> grtr3 = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([&](){ std::cout << <span class="stringliteral">"i>3\n"</span>; }); </div>
<div class="line"> </div>
<div class="line">initi.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(cond1);</div>
<div class="line">cond1.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(equl1, cond2); <span class="comment">// goes to cond2 if i>1</span></div>
<div class="line">cond2.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(equl2, cond3); <span class="comment">// goes to cond3 if i>2</span></div>
<div class="line">cond3.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(equl3, grtr3); <span class="comment">// goes to grtr3 if i>3</span></div>
</div><!-- fragment --><div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_conditional-tasking-nested-if-else.svg" width="1304" height="203"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<h2><a class="anchor" id="ImplementSwitchControlFlow"></a>
Implement Switch Control Flow</h2>
<p>You can use condition tasks to implement <em>switch-style</em> control flow. The following example demonstrates this by creating a switch structure that randomly selects and executes one of three cases using four condition tasks.</p>
<div class="fragment"><div class="line"><a class="code hl_class" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div>
<div class="line"> </div>
<div class="line"><span class="keyword">auto</span> [source, swcond, case1, case2, case3, target] = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>(</div>
<div class="line"> [](){ std::cout << <span class="stringliteral">"source\n"</span>; },</div>
<div class="line"> [](){ std::cout << <span class="stringliteral">"switch\n"</span>; <span class="keywordflow">return</span> rand()%3; },</div>
<div class="line"> [](){ std::cout << <span class="stringliteral">"case 1\n"</span>; <span class="keywordflow">return</span> 0; },</div>
<div class="line"> [](){ std::cout << <span class="stringliteral">"case 2\n"</span>; <span class="keywordflow">return</span> 0; },</div>
<div class="line"> [](){ std::cout << <span class="stringliteral">"case 3\n"</span>; <span class="keywordflow">return</span> 0; },</div>
<div class="line"> [](){ std::cout << <span class="stringliteral">"target\n"</span>; }</div>
<div class="line">);</div>
<div class="line"> </div>
<div class="line">source.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(swcond);</div>
<div class="line">swcond.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(case1, case2, case3);</div>
<div class="line">target.<a class="code hl_function" href="classtf_1_1Task.html#a331b1b726555072e7c7d10941257f664">succeed</a>(case1, case2, case3);</div>
</div><!-- fragment --><div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_conditional-tasking-switch.svg" width="612" height="203"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>Assuming <code>swcond</code> returns 1, the program outputs:</p>
<div class="fragment"><div class="line">source</div>
<div class="line">switch</div>
<div class="line">case 2</div>
<div class="line">target</div>
</div><!-- fragment --><p>Keep in mind, both switch and case tasks must be described as condition tasks. The following implementation is a common mistake in which case tasks are not described as condition tasks.</p>
<div class="fragment"><div class="line"><span class="comment">// wrong implementation of switch control flow using only one condition task</span></div>
<div class="line"><a class="code hl_class" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div>
<div class="line"> </div>
<div class="line"><span class="keyword">auto</span> [source, swcond, case1, case2, case3, target] = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>(</div>
<div class="line"> [](){ std::cout << <span class="stringliteral">"source\n"</span>; },</div>
<div class="line"> [](){ std::cout << <span class="stringliteral">"switch\n"</span>; <span class="keywordflow">return</span> rand()%3; },</div>
<div class="line"> [](){ std::cout << <span class="stringliteral">"case 1\n"</span>; },</div>
<div class="line"> [](){ std::cout << <span class="stringliteral">"case 2\n"</span>; },</div>
<div class="line"> [](){ std::cout << <span class="stringliteral">"case 3\n"</span>; },</div>
<div class="line"> [](){ std::cout << <span class="stringliteral">"target\n"</span>; } <span class="comment">// target has three strong dependencies</span></div>
<div class="line">);</div>
<div class="line"> </div>
<div class="line">source.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(swcond);</div>
<div class="line">swcond.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(case1, case2, case3);</div>
<div class="line">target.<a class="code hl_function" href="classtf_1_1Task.html#a331b1b726555072e7c7d10941257f664">succeed</a>(case1, case2, case3);</div>
</div><!-- fragment --><div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_conditional-tasking-switch-wrong.svg" width="567" height="203"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>In this faulty implementation, task <code>target</code> has three strong dependencies but only one of them will be met. This is because <code>swcond</code> is a condition task, and only one case task will be executed depending on the return of <code>swcond</code>.</p>
<h2><a class="anchor" id="ImplementDoWhileLoopControlFlow"></a>
Implement Do-While-Loop Control Flow</h2>
<p>You can use conditional tasking to implement <em>do-while-loop</em> control flow. The following example creates a do-while-loop control flow diagram that repeatedly increments variable <code>i</code> five times using one condition task.</p>
<div class="fragment"><div class="line"><a class="code hl_class" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">int</span> i;</div>
<div class="line"> </div>
<div class="line"><span class="keyword">auto</span> [init, body, cond, done] = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>(</div>
<div class="line"> [&](){ std::cout << <span class="stringliteral">"i=0\n"</span>; i=0; },</div>
<div class="line"> [&](){ std::cout << <span class="stringliteral">"i++ => i="</span>; i++; },</div>
<div class="line"> [&](){ std::cout << i << <span class="charliteral">'\n'</span>; <span class="keywordflow">return</span> i<5 ? 0 : 1; },</div>
<div class="line"> [&](){ std::cout << <span class="stringliteral">"done\n"</span>; }</div>
<div class="line">); </div>
<div class="line"> </div>
<div class="line">init.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(body);</div>
<div class="line">body.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(cond);</div>
<div class="line">cond.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(body, done);</div>
</div><!-- fragment --><div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_conditional-tasking-do-while.svg" width="596" height="62"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>The program outputs:</p>
<div class="fragment"><div class="line">i=0</div>
<div class="line">i++ => i=1</div>
<div class="line">i++ => i=2</div>
<div class="line">i++ => i=3</div>
<div class="line">i++ => i=4</div>
<div class="line">i++ => i=5</div>
<div class="line">done</div>
</div><!-- fragment --><h2><a class="anchor" id="ImplementWhileLoopControlFlow"></a>
Implement While-Loop Control Flow</h2>
<p>You can use conditional tasking to implement <em>while-loop</em> control flow. The following example creates a while-loop control flow diagram that repeatedly increments variable <code>i</code> five times using two condition task.</p>
<div class="fragment"><div class="line"><a class="code hl_class" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">int</span> i;</div>
<div class="line"> </div>
<div class="line"><span class="keyword">auto</span> [init, cond, body, back, done] = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>(</div>
<div class="line"> [&](){ std::cout << <span class="stringliteral">"i=0\n"</span>; i=0; },</div>
<div class="line"> [&](){ std::cout << <span class="stringliteral">"while i<5\n"</span>; <span class="keywordflow">return</span> i < 5 ? 0 : 1; },</div>
<div class="line"> [&](){ std::cout << <span class="stringliteral">"i++="</span> << i++ << <span class="charliteral">'\n'</span>; },</div>
<div class="line"> [&](){ std::cout << <span class="stringliteral">"back\n"</span>; <span class="keywordflow">return</span> 0; },</div>
<div class="line"> [&](){ std::cout << <span class="stringliteral">"done\n"</span>; }</div>
<div class="line">);</div>
<div class="line"> </div>
<div class="line">init.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(cond);</div>
<div class="line">cond.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(body, done);</div>
<div class="line">body.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(back);</div>
<div class="line">back.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(cond);</div>
</div><!-- fragment --><div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_conditional-tasking-while.svg" width="599" height="186"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>The program outputs:</p>
<div class="fragment"><div class="line">i=0</div>
<div class="line">while i<5</div>
<div class="line">i++=0</div>
<div class="line">back</div>
<div class="line">while i<5</div>
<div class="line">i++=1</div>
<div class="line">back</div>
<div class="line">while i<5</div>
<div class="line">i++=2</div>
<div class="line">back</div>
<div class="line">while i<5</div>
<div class="line">i++=3</div>
<div class="line">back</div>
<div class="line">while i<5</div>
<div class="line">i++=4</div>
<div class="line">back</div>
<div class="line">while i<5</div>
<div class="line">done</div>
</div><!-- fragment --><p>Notice that, when you implement a while-loop block, you cannot direct a dependency from the body task to the loop condition task. Doing so will introduce a strong dependency between the body task and the loop condition task, and the loop condition task will never be executed. The following code shows a common faulty implementation of while-loop control flow.</p>
<div class="fragment"><div class="line"><span class="comment">// wrong implementation of while-loop using only one condition task</span></div>
<div class="line"><a class="code hl_class" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">int</span> i;</div>
<div class="line"> </div>
<div class="line"><span class="keyword">auto</span> [init, cond, body, done] = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>(</div>
<div class="line"> [&](){ std::cout << <span class="stringliteral">"i=0\n"</span>; i=0; },</div>
<div class="line"> [&](){ std::cout << <span class="stringliteral">"while i<5\n"</span>; <span class="keywordflow">return</span> i < 5 ? 0 : 1; },</div>
<div class="line"> [&](){ std::cout << <span class="stringliteral">"i++="</span> << i++ << <span class="charliteral">'\n'</span>; },</div>
<div class="line"> [&](){ std::cout << <span class="stringliteral">"done\n"</span>; }</div>
<div class="line">);</div>
<div class="line"> </div>
<div class="line">init.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(cond);</div>
<div class="line">cond.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(body, done);</div>
<div class="line">body.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(cond);</div>
</div><!-- fragment --><div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_conditional-tasking-while-wrong.svg" width="443" height="143"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>In the taskflow diagram above, the scheduler starts with <code>init</code> and then decrements the strong dependency of the loop condition task, <code>while i<5</code>. After this, there remains one strong dependency, i.e., introduced by the loop body task, <code>i++</code>. However, task <code>i++</code> will not be executed until the loop condition task returns <code>0</code>, causing a deadlock.</p>
<h1><a class="anchor" id="CreateAMultiConditionTask"></a>
Create a Multi-condition Task</h1>
<p>A <em>multi-condition task</em> is a generalized version of conditional tasking. In some cases, applications need to jump to multiple branches from a parent task. This can be done by creating a <em>multi-condition task</em> which allows a task to select one or more successor tasks to execute. Similar to a condition task, a multi-condition task returns a vector of integer indices that indicate the successors to execute when the multi-condition task completes. The index is defined with respect to the order of successors preceded by a multi-condition task. For example, the following code creates a multi-condition task, <code>A</code>, that informs the scheduler to run on its two successors, <code>B</code> and <code>D</code>.</p>
<div class="fragment"><div class="line"><a class="code hl_class" href="classtf_1_1Executor.html">tf::Executor</a> executor;</div>
<div class="line"><a class="code hl_class" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div>
<div class="line"> </div>
<div class="line"><span class="keyword">auto</span> A = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([&]() -> <a class="code hl_class" href="classtf_1_1SmallVector.html">tf::SmallVector<int></a> { </div>
<div class="line"> std::cout << <span class="stringliteral">"A\n"</span>; </div>
<div class="line"> <span class="keywordflow">return</span> {0, 2};</div>
<div class="line">}).name(<span class="stringliteral">"A"</span>);</div>
<div class="line"><span class="keyword">auto</span> B = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([&](){ std::cout << <span class="stringliteral">"B\n"</span>; }).name(<span class="stringliteral">"B"</span>);</div>
<div class="line"><span class="keyword">auto</span> C = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([&](){ std::cout << <span class="stringliteral">"C\n"</span>; }).name(<span class="stringliteral">"C"</span>);</div>
<div class="line"><span class="keyword">auto</span> D = taskflow.<a class="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([&](){ std::cout << <span class="stringliteral">"D\n"</span>; }).name(<span class="stringliteral">"D"</span>);</div>
<div class="line"> </div>
<div class="line">A.<a class="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(B, C, D);</div>
<div class="line"> </div>
<div class="line">executor.<a class="code hl_function" href="classtf_1_1Executor.html#a519777f5783981d534e9e53b99712069">run</a>(taskflow).wait();</div>
<div class="ttc" id="aclasstf_1_1Executor_html"><div class="ttname"><a href="classtf_1_1Executor.html">tf::Executor</a></div><div class="ttdoc">class to create an executor</div><div class="ttdef"><b>Definition</b> executor.hpp:62</div></div>
<div class="ttc" id="aclasstf_1_1Executor_html_a519777f5783981d534e9e53b99712069"><div class="ttname"><a href="classtf_1_1Executor.html#a519777f5783981d534e9e53b99712069">tf::Executor::run</a></div><div class="ttdeci">tf::Future< void > run(Taskflow &taskflow)</div><div class="ttdoc">runs a taskflow once</div></div>
<div class="ttc" id="aclasstf_1_1SmallVector_html"><div class="ttname"><a href="classtf_1_1SmallVector.html">tf::SmallVector</a></div><div class="ttdoc">class to define a vector optimized for small array</div><div class="ttdef"><b>Definition</b> small_vector.hpp:931</div></div>
</div><!-- fragment --><div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_multi-condition-task-1.svg" width="275" height="178"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<dl class="section note"><dt>Note</dt><dd>The return type of a multi-condition task is <a class="el" href="classtf_1_1SmallVector.html" title="class to define a vector optimized for small array">tf::SmallVector</a>, which provides C++ vector-style functionalities but comes with small buffer optimization. </dd></dl>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.13.1-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="Cookbook.html">Cookbook</a></li>
<li class="footer">
Maintained by <a href="https://tsung-wei-huang.github.io/">Dr. Tsung-Wei Huang</a>
—
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.1
</li>
</ul>
</div>