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 is a thread-safe object that 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 with 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 to run multiple taskflows where each taskflow represents a part 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.

// Declare an executor and a taskflow
tf::Executor executor;
tf::Taskflow taskflow;

// Add three tasks into the taskflow
tf::Task A = taskflow.emplace([] () { std::cout << "This is TaskA\n"; });
tf::Task B = taskflow.emplace([] () { std::cout << "This is TaskB\n"; });
tf::Task C = taskflow.emplace([] () { std::cout << "This is TaskC\n"; });

// Build precedence between tasks
A.precede(B, C); 

std::future<void> fu = executor.run(taskflow);
fu.wait();                // block until the execution completes

executor.run(taskflow, [](){ std::cout << "end of one execution\n"; }).wait();
executor.run_n(taskflow, 4);
executor.wait_for_all();  // block until all associated executions finish
executor.run_n(taskflow, 4, [](){ std::cout << "end of four executions\n"; }).wait();
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::wait 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::Executor::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 the same taskflow will automatically synchronize to a sequential chain of executions in the order of 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.

Thread Safety

tf::Executor is thread-safe. Touching an executor from multiple threads is acceptable. You can have multiple threads call executor to run different taskflows.

tf::Executor executor;

for(int i=0; i<10; ++i) {
  std::thread([i, &](){
    // ... modify my taskflow
    executor.run(taskflows[i]);  // run my taskflow
  }).detach();
}

Although executor can be accessed from multiple threads, returnning from wait_for_all will only guarantee those runs that were called before to complete.

Monitor Thread Activities

Inspecting the thread activities is very important for performance analysis. It allows you to know when each task starts and ends participating in the task scheduling. Cpp-Taskflow provides a default observer class tf::ExecutorObserver for this purpose. The following example shows how to create an observer from an executor.

tf::Executor executor;

tf::ExecutorObserver* observer = executor.make_observer<tf::ExecutorObserver>();

Note that each executor can only have an observer at a time. An observer will automatically record the start and end timestamps of each executed task. Users can query, dump or remove the timestamps through the tf::ExecutorObserver::num_tasks, tf::ExecutorObserver::dump and tf::ExecutorObserver::clear methods.

tf::Executor executor;
tf::ExecutorObserver* observer = executor.make_observer<tf::ExecutorObserver>();

executor.run(taskflow).get();  // do something

// Query the total number of tasks (number of timestamp pairs)
auto num_tasks = observer->num_tasks();

// Dump the timeline data in JSON format 
std::string timelines_in_json = observer->dump();

// Clear the timeline data
observer->clear();

Debrief:

Line 2-4 creates an observer and a task dependency graph with four tasks and dispatch the tasks to execution.
Line 7 query the total number of tasks (number of timestamp pair) through observer
Line 10 dump the timestamps to a std::string in JSON format
Line 13 remove all timestamps in the observer

You can visualize the timeline data in a Chrome browser:

Step 1: save the JSON timeline data to a file
Step 2: launch the Chrome browser and open a tab with the url: chrome://tracing
Step 3: load the JSON file

Tasks will be categorized by the executing thread and each task is named with i_j where i is the thread id and j is the task number. You can pan or zoom in/out the timeline to get a detailed view.

Customize Your Own Observer

You can derive your own observer from the base interface class tf::ExecutorObserverInterface to customize the observing methods.