<ahref="#JoinASubflow">Join a Subflow Explicitly</a>
</li>
<liclass="level1">
<ahref="#CreateANestedSubflow">Create a Nested Subflow</a>
</li>
</ul>
</div>
<divclass="textblock"><p>It is very common for a parallel program to spawn task dependency graphs at runtime. In Taskflow, we call this <em>subflow tasking</em>.</p>
<h1><aclass="anchor" id="CreateASubflow"></a>
Create a Subflow</h1>
<p>Subflow tasks are those created during the execution of a graph. These tasks are spawned from a parent task and are grouped together to a <em>subflow</em> dependency graph. To create a subflow, emplace a callable that takes an argument of type <aclass="el" href="classtf_1_1Subflow.html" title="class to construct a subflow graph from the execution of a dynamic task">tf::Subflow</a>. A <aclass="el" href="classtf_1_1Subflow.html" title="class to construct a subflow graph from the execution of a dynamic task">tf::Subflow</a> object will be created and forwarded to the execution context of the task. All methods you find in <aclass="el" href="classtf_1_1Taskflow.html" title="class to create a taskflow object">tf::Taskflow</a> are applicable for <aclass="el" href="classtf_1_1Subflow.html" title="class to construct a subflow graph from the execution of a dynamic task">tf::Subflow</a>.</p>
<divclass="line">16: A.<aclass="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(B); <spanclass="comment">// B runs after A</span></div>
<divclass="line">17: A.<aclass="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(C); <spanclass="comment">// C runs after A</span></div>
<divclass="line">18: B.<aclass="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(D); <spanclass="comment">// D runs after B</span></div>
<divclass="line">19: C.<aclass="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(D); <spanclass="comment">// D runs after C</span></div>
<divclass="line">20:</div>
<divclass="line">21: executor.<aclass="code hl_function" href="classtf_1_1Executor.html#a519777f5783981d534e9e53b99712069">run</a>(taskflow).get(); <spanclass="comment">// execute the graph to spawn the subflow</span></div>
<divclass="ttc" id="aclasstf_1_1Executor_html"><divclass="ttname"><ahref="classtf_1_1Executor.html">tf::Executor</a></div><divclass="ttdoc">class to create an executor</div><divclass="ttdef"><b>Definition</b> executor.hpp:62</div></div>
<divclass="ttc" id="aclasstf_1_1Executor_html_a519777f5783981d534e9e53b99712069"><divclass="ttname"><ahref="classtf_1_1Executor.html#a519777f5783981d534e9e53b99712069">tf::Executor::run</a></div><divclass="ttdeci">tf::Future< void > run(Taskflow &taskflow)</div><divclass="ttdoc">runs a taskflow once</div></div>
<divclass="ttc" id="aclasstf_1_1FlowBuilder_html_a4d52a7fe2814b264846a2085e931652c"><divclass="ttname"><ahref="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">tf::FlowBuilder::emplace</a></div><divclass="ttdeci">Task emplace(C &&callable)</div><divclass="ttdoc">creates a static task</div><divclass="ttdef"><b>Definition</b> flow_builder.hpp:1781</div></div>
<divclass="ttc" id="aclasstf_1_1Task_html"><divclass="ttname"><ahref="classtf_1_1Task.html">tf::Task</a></div><divclass="ttdoc">class to create a task handle over a taskflow node</div><divclass="ttdef"><b>Definition</b> task.hpp:569</div></div>
<divclass="ttc" id="aclasstf_1_1Task_html_a8c78c453295a553c1c016e4062da8588"><divclass="ttname"><ahref="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">tf::Task::precede</a></div><divclass="ttdeci">Task & precede(Ts &&... tasks)</div><divclass="ttdoc">adds precedence links from this to other tasks</div><divclass="ttdef"><b>Definition</b> task.hpp:1305</div></div>
<divclass="ttc" id="aclasstf_1_1Taskflow_html"><divclass="ttname"><ahref="classtf_1_1Taskflow.html">tf::Taskflow</a></div><divclass="ttdoc">class to create a taskflow object</div><divclass="ttdef"><b>Definition</b> taskflow.hpp:64</div></div>
</div><!-- fragment --><divclass="dotgraph">
<iframescrolling="no" frameborder="0" src="dot_subflow-join.svg" width="496" height="320"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>Debrief: </p><ul>
<li>Lines 1-2 create a taskflow and an executor </li>
<li>Lines 4-6 create three tasks, A, C, and D </li>
<li>Lines 8-14 create a task B that spawns a task dependency graph of three tasks B1, B2, and B3 </li>
<li>Lines 16-19 add dependencies among A, B, C, and D </li>
<li>Line 21 submits the graph to an executor and waits until it finishes</li>
</ul>
<p>Lines 8-14 are the main block to enable subflow tasking at task B. The runtime will create a <aclass="el" href="classtf_1_1Subflow.html" title="class to construct a subflow graph from the execution of a dynamic task">tf::Subflow</a> passing it to task B, and spawn a dependency graph as described by the associated callable. This new subflow graph will be added to the topology of its parent task B.</p>
<h1><aclass="anchor" id="RetainASubflow"></a>
Retain a Subflow</h1>
<p>By default, a <aclass="el" href="classtf_1_1Subflow.html" title="class to construct a subflow graph from the execution of a dynamic task">tf::Subflow</a> automatically clears its internal task graph once it is joined. After a subflow joins, its structure and associated resources are no longer accessible. This behavior is designed to reduce memory usage, particularly in applications that recursively spawn many subflows. For applications that require post-processing, such as visualizing the subflow through <aclass="el" href="classtf_1_1Taskflow.html#ac433018262e44b12c4cc9f0c4748d758" title="dumps the taskflow to a DOT format through a std::ostream target">tf::Taskflow::dump</a>, users can disable this default cleanup behavior by calling <aclass="el" href="classtf_1_1Subflow.html#ac585638d8ca8fb2f34c4826cb0d4f39f" title="specifies whether to keep the subflow after it is joined">tf::Subflow::retain</a> on <code>true</code>. This instructs the runtime to retain the subflow's task graph even after it has joined, enabling further inspection or visualization.</p>
<divclass="line"> sf.<aclass="code hl_function" href="classtf_1_1Subflow.html#ac585638d8ca8fb2f34c4826cb0d4f39f">retain</a>(<spanclass="keyword">true</span>); <spanclass="comment">// retain the subflow after join for visualization</span></div>
<divclass="line"><spanclass="keyword">auto</span> A = sf.<aclass="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){ std::cout << <spanclass="stringliteral">"A\n"</span>; });</div>
<divclass="line"><spanclass="keyword">auto</span> B = sf.<aclass="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){ std::cout << <spanclass="stringliteral">"B\n"</span>; });</div>
<divclass="line"><spanclass="keyword">auto</span> C = sf.<aclass="code hl_function" href="classtf_1_1FlowBuilder.html#a4d52a7fe2814b264846a2085e931652c">emplace</a>([](){ std::cout << <spanclass="stringliteral">"C\n"</span>; });</div>
<divclass="line"> A.<aclass="code hl_function" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(B, C); <spanclass="comment">// A runs before B and C</span></div>
<divclass="ttc" id="aclasstf_1_1Subflow_html"><divclass="ttname"><ahref="classtf_1_1Subflow.html">tf::Subflow</a></div><divclass="ttdoc">class to construct a subflow graph from the execution of a dynamic task</div><divclass="ttdef"><b>Definition</b> flow_builder.hpp:1956</div></div>
<divclass="ttc" id="aclasstf_1_1Subflow_html_ac585638d8ca8fb2f34c4826cb0d4f39f"><divclass="ttname"><ahref="classtf_1_1Subflow.html#ac585638d8ca8fb2f34c4826cb0d4f39f">tf::Subflow::retain</a></div><divclass="ttdeci">void retain(bool flag) noexcept</div><divclass="ttdoc">specifies whether to keep the subflow after it is joined</div><divclass="ttdef"><b>Definition</b> flow_builder.hpp:2065</div></div>
<divclass="ttc" id="aclasstf_1_1Taskflow_html_ac433018262e44b12c4cc9f0c4748d758"><divclass="ttname"><ahref="classtf_1_1Taskflow.html#ac433018262e44b12c4cc9f0c4748d758">tf::Taskflow::dump</a></div><divclass="ttdeci">void dump(std::ostream &ostream) const</div><divclass="ttdoc">dumps the taskflow to a DOT format through a std::ostream target</div><divclass="ttdef"><b>Definition</b> taskflow.hpp:433</div></div>
</div><!-- fragment --><h1><aclass="anchor" id="JoinASubflow"></a>
Join a Subflow Explicitly</h1>
<p>By default, a subflow <em>implicitly</em> joins its parent task when execution leaves its context. All terminal nodes (i.e., nodes with no outgoing edges) in the subflow are guaranteed to precede the parent task. Upon joining, the subflow's task graph and associated resources are automatically cleaned up. If your application needs to access variables defined within the subflow after it joins, you can explicitly join the subflow and handle post-processing accordingly. A common use case is parallelizing recursive computations such as the Fibonacci sequence:</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">int</span> spawn(<spanclass="keywordtype">int</span> n, <aclass="code hl_class" href="classtf_1_1Subflow.html">tf::Subflow</a>& sbf) {</div>
<divclass="ttc" id="aclasstf_1_1Subflow_html_a59fcac1323e70d920088dd37bd0be245"><divclass="ttname"><ahref="classtf_1_1Subflow.html#a59fcac1323e70d920088dd37bd0be245">tf::Subflow::join</a></div><divclass="ttdeci">void join()</div><divclass="ttdoc">enables the subflow to join its parent task</div></div>
</div><!-- fragment --><p>The code above computes the fifth Fibonacci number using recursive subflow. Calling <aclass="el" href="classtf_1_1Subflow.html#a59fcac1323e70d920088dd37bd0be245" title="enables the subflow to join its parent task">tf::Subflow::join</a><em>immediately</em> materializes the subflow by executing all associated tasks to recursively compute Fibonacci numbers. The taskflow graph is shown below:</p>
<divclass="dotgraph">
<iframescrolling="no" frameborder="0" src="dot_fibonacci_7.svg" width="894" height="752"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<dlclass="section note"><dt>Note</dt><dd>Using <aclass="el" href="classtf_1_1Subflow.html" title="class to construct a subflow graph from the execution of a dynamic task">tf::Subflow</a> to implement recursive parallelism like finding Fibonacci numbers may not be as efficient as <aclass="el" href="classtf_1_1Runtime.html" title="class to create a runtime task">tf::Runtime</a> due to additional task graph overhead. For more details, readers can refer to <aclass="el" href="ExamplesFibonacciNumber.html">Fibonacci Number</a></dd></dl>
<iframescrolling="no" frameborder="0" src="dot_nested_subflow.svg" width="542" height="303"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>Debrief: </p><ul>
<li>Line 1 creates a taskflow object </li>
<li>Lines 3-20 create a task to spawn a subflow of two tasks A1 and A2 </li>
<li>Lines 9-18 spawn another subflow of two tasks A2_1 and A2_2 out of its parent task A2 </li>
<li>Lines 23 runs the defined taskflow graph</li>
</ul>
<dlclass="section note"><dt>Note</dt><dd>To properly visualize subflows, you must call <aclass="el" href="classtf_1_1Subflow.html#ac585638d8ca8fb2f34c4826cb0d4f39f" title="specifies whether to keep the subflow after it is joined">tf::Subflow::retain</a> on each subflow and execute the taskflow once to ensure all associated subflows are spawned. </dd></dl>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.13.1-->
<!-- start footer part -->
<divid="nav-path" class="navpath"><!-- id is needed for treeview function! -->