taskflow-cpp/docs/StaticTasking.html at master · baileyfu/taskflow-cpp

History

259 lines (255 loc) · 47 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

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

<!DOCTYPE html>

<head>

<title>Cookbook » Static Tasking | Taskflow QuickStart</title>

</head>

<body>

<a href="https://taskflow.github.io"><img src="taskflow_logo.png" alt="" />Taskflow</a> | <a href="index.html" class="m-thin">QuickStart</a>

</svg></a>

</div>

<li><a href="pages.html">Handbook</a></li>

<li><a href="namespaces.html">Namespaces</a></li>

</ol>

<li><a href="annotated.html">Classes</a></li>

<li><a href="files.html">Files</a></li>

</svg></a></li>

</ol>

</div>

</nav></header>

<h1>

<a href="Cookbook.html">Cookbook</a> »

Static Tasking

</h1>

<h3>Contents</h3>

<ul>

<li><a href="#CreateATaskDependencyGraph">Create a Task Dependency Graph</a></li>

<li><a href="#VisualizeATaskDependencyGraph">Visualize a Task Dependency Graph</a></li>

<li><a href="#ModifyTaskAttributes">Modify Task Attributes</a></li>

<li><a href="#TraverseAdjacentTasks">Traverse Adjacent Tasks</a></li>

<li><a href="#AttachUserDataToATask">Attach User Data to a Task</a></li>

<li><a href="#UnderstandTheLifetimeOfATask">Understand the Lifetime of a Task</a></li>

<li><a href="#MoveATaskflow">Move a Taskflow</a></li>

</ul>

</nav>

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.<section id="CreateATaskDependencyGraph"><h2><a href="#CreateATaskDependencyGraph">Create a Task Dependency Graph</a></h2>A task in Taskflow is a callable object for which the operation <a href="https://en.cppreference.com/w/cpp/utility/functional/invoke">std::invoke</a> is applicable. It can be either a functor, a lambda expression, a bind expression, or a class objects with <code>operator()</code> overloaded. All tasks are created from <a href="classtf_1_1Taskflow.html" class="m-doc">tf::Taskflow</a>, the class that manages a task dependency graph. Taskflow provides two methods, <a href="classtf_1_1FlowBuilder.html#acab0b4ac82260f47fdb36a3244ee3aaf" class="m-doc">tf::Taskflow::placeholder</a> and <a href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57" class="m-doc">tf::Taskflow::emplace</a> to create a task.<pre class="m-code">1: tf::Taskflow taskflow;

2: tf::Task A = taskflow.placeholder();

3: tf::Task B = taskflow.emplace([] () { std::cout << "task B\n"; });

4:

5: auto [D, E, F] = taskflow.emplace(

6: [](){ std::cout << "Task A\n"; },

7: [](){ std::cout << "Task B\n"; },

8: [](){ std::cout << "Task C\n"; }

9: );</pre>Debrief:<ul><li>Line 1 creates a taskflow object, or a graph</li><li>Line 2 creates a placeholder task without work (i.e., callable)</li><li>Line 3 creates a task from a given callable object and returns a task handle</li><li>Lines 5-9 create three tasks in one call using C++ structured binding coupled with <a href="http://en.cppreference.com/w/cpp/utility/tuple.html" class="m-doc-external">std::tuple</a></li></ul>Each time you create a task, the taskflow object creates a node in the task graph and returns a task handle of type <a href="classtf_1_1Task.html" class="m-doc">tf::Task</a>. 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.<pre class="m-code"> 1: tf::Taskflow taskflow;

2: tf::Task A = taskflow.emplace([] () { std::cout << "create a task A\n"; });

3: tf::Task B = taskflow.emplace([] () { std::cout << "create a task B\n"; });

4:

5: A.name("TaskA");

6: A.work([] () { std::cout << "reassign A to a new callable\n"; });

7: A.precede(B);

8:

9: std::cout << A.name() << std::endl; // TaskA

10: std::cout << A.num_successors() << std::endl; // 1

11: std::cout << A.num_dependents() << std::endl; // 0

12:

13: std::cout << B.num_successors() << std::endl; // 0

14: std::cout << B.num_dependents() << std::endl; // 1</pre>Debrief:<ul><li>Line 1 creates a taskflow object</li><li>Lines 2-3 create two tasks A and B</li><li>Lines 5-6 assign a name and a work to task A, and add a precedence link to task B</li><li>Line 7 adds a dependency link from A to B</li><li>Lines 9-14 dump the task attributes</li></ul>Taskflow uses general-purpose polymorphic function wrapper, <a href="http://en.cppreference.com/w/cpp/utility/functional/function.html" class="m-doc-external">std::function</a>, 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:<pre class="m-code">taskflow.emplace([ptr=std::make_unique<int>(1)](){

});</pre></section><section id="VisualizeATaskDependencyGraph"><h2><a href="#VisualizeATaskDependencyGraph">Visualize a Task Dependency Graph</a></h2>You can dump a taskflow to a DOT format and visualize the graph using free online tools such as <a href="https://dreampuf.github.io/GraphvizOnline/">GraphvizOnline</a> and <a href="http://www.webgraphviz.com/">WebGraphviz</a>.<pre class="m-code"> 1: #include <taskflow/taskflow.hpp>

2:

3: int main() {

4:

5: tf::Taskflow taskflow;

6:

7: // create a task dependency graph

8: tf::Task A = taskflow.emplace([] () { std::cout << "Task A\n"; });

9: tf::Task B = taskflow.emplace([] () { std::cout << "Task B\n"; });

10: tf::Task C = taskflow.emplace([] () { std::cout << "Task C\n"; });

11: tf::Task D = taskflow.emplace([] () { std::cout << "Task D\n"; });

12:

13: // add dependency links

14: A.precede(B);

15: A.precede(C);

16: B.precede(D);

17: C.precede(D);

18:

19: taskflow.dump(std::cout);

20: }</pre>Debrief:<ul><li>Line 5 creates a taskflow object</li><li>Lines 8-11 create four tasks</li><li>Lines 14-17 add four task dependencies</li><li>Line 19 dumps the taskflow in the DOT format through standard output</li></ul><div class="m-graph"><svg style="width: 15.125rem; height: 6.250rem;" viewBox="0.00 0.00 242.00 99.77">

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</svg>

</div></section><section id="ModifyTaskAttributes"><h2><a href="#ModifyTaskAttributes">Modify Task Attributes</a></h2>This example demonstrates how to modify a task's attributes using methods defined in the task handler.<pre class="m-code"> 1: #include <taskflow/taskflow.hpp>

2:

4:

6:

7: std::vector<tf::Task> tasks = {

8: taskflow.placeholder(), // create a task with no work

9: taskflow.placeholder() // create a task with no work

10: };

11:

12: tasks[0].name("This is Task 0");

13: tasks[1].name("This is Task 1");

14: tasks[0].precede(tasks[1]);

15:

16: for(auto task : tasks) { // print out each task's attributes

17: std::cout << task.name() << ": "

18: << "num_dependents=" << task.num_dependents() << ", "

19: << "num_successors=" << task.num_successors() << '\n';

20: }

21:

22: taskflow.dump(std::cout); // dump the taskflow graph

23:

24: tasks[0].work([](){ std::cout << "got a new work!\n"; });

25: tasks[1].work([](){ std::cout << "got a new work!\n"; });

26:

27: return 0;

28: }</pre>The output of this program looks like the following:<pre class="m-code">This is Task 0: num_dependents=0, num_successors=1

This is Task 1: num_dependents=1, num_successors=0

digraph Taskflow {

"This is Task 1";

"This is Task 0";

"This is Task 0" -> "This is Task 1";

}</pre>Debrief:<ul><li>Line 5 creates a taskflow object</li><li>Lines 7-10 create two placeholder tasks with no works and stores the corresponding task handles in a vector</li><li>Lines 12-13 name the two tasks with human-readable strings</li><li>Line 14 adds a dependency link from the first task to the second task</li><li>Lines 16-20 print out the name of each task, the number of dependents, and the number of successors</li><li>Line 22 dumps the task dependency graph to a <a href="https://dreampuf.github.io/GraphvizOnline/">GraphViz Online</a> format (dot)</li><li>Lines 24-25 assign a new target to each task</li></ul>You can change the name and work of a task at anytime before running the graph. The later assignment overwrites the previous values.</section><section id="TraverseAdjacentTasks"><h2><a href="#TraverseAdjacentTasks">Traverse Adjacent Tasks</a></h2>You can iterate the successor list and the dependent list of a task by using <a href="classtf_1_1Task.html#aff13a503d4a3c994eb08cb6f22e1b427" class="m-doc">tf::Task::for_each_successor</a> and <a href="classtf_1_1Task.html#a3bf68937662bf291637e4a763476b2e4" class="m-doc">tf::Task::for_each_dependent</a>, respectively. Each method takes a lambda and applies it to a successor or a dependent being traversed.<pre class="m-code">// traverse all successors of my_task

my_task.for_each_successor([s=0] (tf::Task successor) mutable {

std::cout << "successor " << s++ << '\n';

});

// traverse all dependents of my_task

my_task.for_each_dependent([d=0] (tf::Task dependent) mutable {

std::cout << "dependent " << d++ << '\n';

});</pre></section><section id="AttachUserDataToATask"><h2><a href="#AttachUserDataToATask">Attach User Data to a Task</a></h2>You can attach custom data to a task using <a href="classtf_1_1Task.html#afd82ab6d6518d1142a72c4d2c97ff114" class="m-doc">tf::Task::data(void*)</a> and access it using <a href="classtf_1_1Task.html#afd82ab6d6518d1142a72c4d2c97ff114" class="m-doc">tf::Task::data()</a>. Each node in a taskflow is associated with a C-styled data pointer (i.e., <code>void*</code>) 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.<pre class="m-code">int my_data = 5;

tf::Task task = taskflow.placeholder();

task.data(&my_data)

.work([task](){

int my_date = *static_cast<int*>(task.data());

std::cout << "my_data: " << my_data;

});</pre>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.<aside class="m-note m-warning"><h4>Attention</h4>It is your responsibility to ensure that the attached data stay alive during the execution of its task.</aside></section><section id="UnderstandTheLifetimeOfATask"><h2><a href="#UnderstandTheLifetimeOfATask">Understand the Lifetime of a Task</a></h2>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.<aside class="m-note m-warning"><h4>Attention</h4>It is your responsibility to keep tasks and graph alive during their execution.</aside></section><section id="MoveATaskflow"><h2><a href="#MoveATaskflow">Move a Taskflow</a></h2>You can construct or assign a taskflow from a moved taskflow. Moving a taskflow to another will result in transferring the underlying graph data structures from one to the other.<pre class="m-code">tf::Taskflow taskflow1, taskflow3;

taskflow1.emplace([](){});

// move-construct taskflow2 from taskflow1

tf::Taskflow taskflow2(std::move(taskflow1));

assert(taskflow2.num_tasks() == 1 && taskflow1.num_tasks() == 0);

// move-assign taskflow3 to taskflow2

taskflow3 = std::move(taskflow2);

assert(taskflow3.num_tasks() == 1 && taskflow2.num_tasks() == 0);</pre>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 <a href="ExecuteTaskflow.html#ExecuteATaskflowWithTransferredOwnership" class="m-doc">Execute a Taskflow with Transferred Ownership</a> for more details.</section>

</div>

</article></main>

<div>Tab / T to search, Esc to close</div>

</div>

<form>

</form>

Search for symbols, directories, files, pages or

modules. You can omit any prefix from the symbol or file path; adding a

<code>:</code> or <code>/</code> suffix lists all members of given symbol or

directory.

Use ↓

/ ↑ to navigate through the list,

Enter to go.

Tab autocompletes common prefix, you can

copy a link to the result using ⌘

L while ⌘

M produces a Markdown link.

</div>

<div id="search-notfound" class="m-text m-warning m-text-center">Sorry, nothing was found.</div>

</div>

Taskflow handbook is part of the <a href="https://taskflow.github.io">Taskflow project</a>, copyright © <a href="https://tsung-wei-huang.github.io/">Dr. Tsung-Wei Huang</a>, 2018–2022. Generated by <a href="https://doxygen.org/">Doxygen</a> 1.8.14 and <a href="https://mcss.mosra.cz/">m.css</a>.

</div>

</nav></footer>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

StaticTasking.html

Latest commit

History

StaticTasking.html

File metadata and controls