<ahref="#CreateAModuleTaskFromATaskflow">Create a Module Task from a Taskflow</a>
</li>
<liclass="level1">
<ahref="#CreateACustomComposableGraph">Create a Custom Composable Graph</a>
</li>
<liclass="level1">
<ahref="#CreateAnAdoptedModuleTask">Create an Adopted Module Task</a>
</li>
</ul>
</div>
<divclass="textblock"><p>Composition is a key to improve the programmability of a complex workflow. This chapter describes how to create a large parallel graph through composition of modular and reusable blocks that are easier to optimize.</p>
<h1><aclass="anchor" id="ComposeATaskflow"></a>
Compose a Taskflow</h1>
<p>A powerful feature of Taskflow is its <em>composable</em> interface. You can break down a large parallel workload into smaller pieces each designed to run a specific task dependency graph. This largely facilitates the <em>modularity</em> of writing a parallel task program.</p>
<divclass="fragment"><divclass="line"><spanclass="comment">// f1 has three independent tasks</span></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_1FlowBuilder_html_ac6f22228d4c2ea2e643c4b0d42c0e92a"><divclass="ttname"><ahref="classtf_1_1FlowBuilder.html#ac6f22228d4c2ea2e643c4b0d42c0e92a">tf::FlowBuilder::composed_of</a></div><divclass="ttdeci">Task composed_of(T &object)</div><divclass="ttdoc">creates a module task for the target object</div><divclass="ttdef"><b>Definition</b> flow_builder.hpp:1831</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_a08ada0425b490997b6ff7f310107e5e3"><divclass="ttname"><ahref="classtf_1_1Task.html#a08ada0425b490997b6ff7f310107e5e3">tf::Task::name</a></div><divclass="ttdeci">const std::string & name() const</div><divclass="ttdoc">queries the name of the task</div><divclass="ttdef"><b>Definition</b> task.hpp:1435</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>
<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>
<divclass="ttc" id="aclasstf_1_1Taskflow_html_ad5706e5819aa01a63c4aa2e3485546b9"><divclass="ttname"><ahref="classtf_1_1Taskflow.html#ad5706e5819aa01a63c4aa2e3485546b9">tf::Taskflow::name</a></div><divclass="ttdeci">void name(const std::string &)</div><divclass="ttdoc">assigns a new name to this taskflow</div><divclass="ttdef"><b>Definition</b> taskflow.hpp:386</div></div>
</div><!-- fragment --><divclass="dotgraph">
<iframescrolling="no" frameborder="0" src="dot_composition_static_1.svg" width="443" height="423"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>The above example first constructs a taskflow consisting of three tasks, <code>f1A</code>, <code>f1B</code>, and <code>f1C</code>, where <code>f1A</code> and <code>f1B</code> execute before <code>f1C</code>. It then creates a second taskflow with four tasks, <code>f2A</code>, <code>f2B</code>, <code>f2C</code>, and <code>f2D</code>. The first taskflow is encapsulated as a module task using <aclass="el" href="classtf_1_1FlowBuilder.html#ac6f22228d4c2ea2e643c4b0d42c0e92a" title="creates a module task for the target object">Taskflow::composed_of</a>, allowing it to be embedded within the second taskflow. Dependencies are then established so that <code>f2C</code> must complete before the module task begins, and the module task must finish before <code>f2D</code> executes, thereby integrating the two taskflows into a single execution graph with well-defined ordering constraints.</p>
<p>The task created from <aclass="el" href="classtf_1_1FlowBuilder.html#ac6f22228d4c2ea2e643c4b0d42c0e92a" title="creates a module task for the target object">Taskflow::composed_of</a> is a <em>module</em> task that runs on a pre-defined taskflow. A module task does not own the taskflow but maintains a soft mapping to the taskflow. You can create multiple module tasks from the same taskflow but only one module task can run at one time. For example, the following composition is valid. Even though the two module tasks <code>module1</code> and <code>module2</code> refer to the same taskflow <code>F1</code>, the dependency link prevents <code>F1</code> from multiple executions at the same time.</p>
<divclass="dotgraph">
<iframescrolling="no" frameborder="0" src="dot_composition_static_2.svg" width="443" height="519"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>However, the following composition is <em>invalid</em>. Both module tasks refer to the same taskflow. They can not run at the same time because they are associated with the same graph.</p>
<divclass="dotgraph">
<iframescrolling="no" frameborder="0" src="dot_composition_static_invalid.svg" width="658" height="423"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
<p>Taskflow allows you to create a custom graph object that can participate in the scheduling using composition. To become a module task, your class <code>T</code> must define the method <code>T::graph()</code> that returns a reference to the <aclass="el" href="classtf_1_1Graph.html" title="class to create a graph object">tf::Graph</a> object managed by <code>T</code>. The following example defines a custom graph object that can be assembled in a taskflow through composition:</p>
<divclass="ttc" id="aclasstf_1_1FlowBuilder_html"><divclass="ttname"><ahref="classtf_1_1FlowBuilder.html">tf::FlowBuilder</a></div><divclass="ttdoc">class to build a task dependency graph</div><divclass="ttdef"><b>Definition</b> flow_builder.hpp:114</div></div>
<divclass="ttc" id="aclasstf_1_1Graph_html"><divclass="ttname"><ahref="classtf_1_1Graph.html">tf::Graph</a></div><divclass="ttdoc">class to create a graph object</div><divclass="ttdef"><b>Definition</b> graph.hpp:47</div></div>
</div><!-- fragment --><p>The above code defines a custom graph that can participate in taskflow composition. The graph object is represented using <aclass="el" href="classtf_1_1Graph.html" title="class to create a graph object">tf::Graph</a>, and its constructor builds the internal task graph through <aclass="el" href="classtf_1_1FlowBuilder.html" title="class to build a task dependency graph">tf::FlowBuilder</a>. To support composition, the graph implements the required interface method (<code><aclass="el" href="classtf_1_1Graph.html" title="class to create a graph object">Graph</a>& graph()</code>) that exposes its internal structure to the Taskflow runtime. Or, you can simply expose the <code>graph</code> and pass it to <aclass="el" href="classtf_1_1FlowBuilder.html#ac6f22228d4c2ea2e643c4b0d42c0e92a" title="creates a module task for the target object">tf::FlowBuilder::composed_of</a> without defining an additional struct.</p>
<divclass="ttc" id="aclasstf_1_1Task_html_ab38be520fe700cb4ca1f312308a95585"><divclass="ttname"><ahref="classtf_1_1Task.html#ab38be520fe700cb4ca1f312308a95585">tf::Task::composed_of</a></div><divclass="ttdeci">Task & composed_of(T &object)</div><divclass="ttdoc">creates a module task from a taskflow</div><divclass="ttdef"><b>Definition</b> task.hpp:1337</div></div>
</div><!-- fragment --><p>With this interface in place, the custom graph can then be instantiated as a module task within a larger taskflow, enabling it to be seamlessly composed and scheduled alongside other tasks.</p>
<dlclass="section note"><dt>Note</dt><dd>Users are responsible for ensuring the given target remains valid throughout its execution. The executor does not assume ownership of the target object.</dd></dl>
<p>Unlike <aclass="el" href="classtf_1_1FlowBuilder.html#ac6f22228d4c2ea2e643c4b0d42c0e92a" title="creates a module task for the target object">tf::FlowBuilder::composed_of</a>, which holds a <em>reference</em> to an externally-owned graph and requires the caller to manage its lifetime, <aclass="el" href="classtf_1_1FlowBuilder.html#a35f6503341d7066ef642e6b1a9d81c2c" title="creates a module task from a graph by taking over its ownership">tf::FlowBuilder::adopt</a> transfers <em>ownership</em> of a <aclass="el" href="classtf_1_1Graph.html" title="class to create a graph object">tf::Graph</a> into the task via move semantics. Once adopted, the graph is owned and managed by the executor for the duration of its execution, and the caller must not access the moved-from graph afterward. The following example creates a graph through <aclass="el" href="classtf_1_1FlowBuilder.html" title="class to build a task dependency graph">tf::FlowBuilder</a> and moves it to a taskflow as an adopted module task:</p>
<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_a35f6503341d7066ef642e6b1a9d81c2c"><divclass="ttname"><ahref="classtf_1_1FlowBuilder.html#a35f6503341d7066ef642e6b1a9d81c2c">tf::FlowBuilder::adopt</a></div><divclass="ttdeci">Task adopt(Graph &&graph)</div><divclass="ttdoc">creates a module task from a graph by taking over its ownership</div><divclass="ttdef"><b>Definition</b> flow_builder.hpp:1838</div></div>
</div><!-- fragment --><p>The adopted module task can participate in the taskflow's dependency graph just like any other module task created via <aclass="el" href="classtf_1_1FlowBuilder.html#ac6f22228d4c2ea2e643c4b0d42c0e92a" title="creates a module task for the target object">tf::FlowBuilder::composed_of</a>. You can chain dependencies before and after it in the usual way:</p>
</div><!-- fragment --><dlclass="section note"><dt>Note</dt><dd>The key distinction between <aclass="el" href="classtf_1_1FlowBuilder.html#ac6f22228d4c2ea2e643c4b0d42c0e92a" title="creates a module task for the target object">tf::Taskflow::composed_of</a> and <aclass="el" href="classtf_1_1FlowBuilder.html#a35f6503341d7066ef642e6b1a9d81c2c" title="creates a module task from a graph by taking over its ownership">tf::Taskflow::adopt</a> is ownership. Use <code>composed_of</code> when the graph is long-lived and shared across multiple taskflows or multiple runs. Use <code>adopt</code> when you want to transfer a graph into the taskflow and let the executor manage its lifetime. </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! -->