Cpp-Taskflow  2.2.0
C2: Execute a Taskflow

After you create a task dependency graph, you need to dispatch it to threads for execution. In this chapter, we will show you how to execute a task dependency graph.

Graph and Topology

Each taskflow object has exactly one graph at a time that represents a set of dependent tasks constructed so far. To execute a graph, you need to create an executor from tf::Executor. An executor manages a set of worker threads and schedules task execution through an efficient work-stealing algorithm. Issuing a call to run a taskflow creates a topology. A topology is a data structure wrapping around a running graph. Each executor object has a list of topologies to keep track of the execution status of running and finished graphs. Users can retrieve this information for graph inspection and debugging.

Create an Executor

The first step is to create an executor to run a taskflow. tf::Executor takes an unsigned integer to construct an executor of N worker threads. The default value is std::thread::hardware_concurrency.

tf::Executor executor1; // create an executor of std::thread::hardware_concurrency worker threads
tf::Executor executor2(4); // create an executor of 4 worker threads

An executor can be reused to execute multiple taskflows. In most workloads, you may need only one executor but multiple taskflows to represent parts of a parallel decomposition.

Execute a Taskflow

tf::Executor provides a set of run_* methods, tf::Executor::run, tf::Executor::run_n, and tf::Executor::run_until to run a taskflow for one time, multiple times, or until a given predicate evaluates to true. All methods accept an optional callback to invoke after the execution completes, and return a std::future for users to access the execution status. The code below shows several ways to run a taskflow.

1: // Declare an executor and a taskflow
2: tf::Executor executor;
3: tf::Taskflow taskflow;
4:
5: // Add three tasks into the taskflow
6: tf::Task A = taskflow.emplace([] () { std::cout << "This is TaskA\n"; });
7: tf::Task B = taskflow.emplace([] () { std::cout << "This is TaskB\n"; });
8: tf::Task C = taskflow.emplace([] () { std::cout << "This is TaskC\n"; });
9:
10: // Build precedence between tasks
11: A.precede(B, C);
12:
13: std::future<void> fu = executor.run(taskflow);
14: fu.get(); // block until the execution completes
15:
16: executor.run(taskflow, [](){ std::cout << "end of one execution\n"; }).get();
17: executor.run_n(taskflow, 4);
18: executor.wait_for_all(); // block until all associated executions finish
19: executor.run_n(taskflow, 4, [](){ std::cout << "end of four executions\n"; }).get();
20: executor.run_until(taskflow, [int cnt=0] () mutable { return (++cnt == 10); });

Debrief:

  • Line 6-8 creates a taskflow of three tasks A, B, and C
  • Line 13-14 runs the taskflow once and use std::future::get to wait for completion
  • Line 16 runs the taskflow once with a callback to invoke when the execution finishes
  • Line 17-18 runs the taskflow four times and use tf::Taskflow::wait_for_all to wait for completion
  • Line 19 runs the taskflow four times and invokes a callback at the end of the forth execution
  • Line 20 keeps running the taskflow until the predicate returns true

Issuing multiple runs on a same taskflow will automatically synchronize to a sequential chain of executions following the order of the run calls.

executor.run(taskflow); // execution 1
executor.run_n(taskflow, 10); // execution 2
executor.run(taskflow); // execution 3
executor.wait_for_all(); // execution 1 -> execution 2 -> execution 3

A key point to notice is a running taskflow must remain alive during its execution. It is your responsibility to ensure a taskflow not being destructed when it is running. For example, the code below can result undefined behavior.

tf::Executor executor; // create an executor
// create a taskflow whose lifetime is restricted by the scope
{
tf::Taskflow taskflow;
// add tasks to the taskflow
// ...
// run the taskflow
executor.run(f);
} // at this point, taskflow might get destructed while it is running, resulting in defined behavior

Similarly, you should avoid touching a taskflow while it is running.

tf::Taskflow taskflow;
// Add tasks into the taskflow
// ...
// Declare an executor
tf::Executor executor;
std::future<void> future = taskflow.run(f); // non-blocking return
// alter the taskflow while running leads to undefined behavior
f.emplace([](){ std::cout << "Add a new task\n"; });

A rule of thumb is to always keep a taskflow alive in your function scope while it is participating in an execution.