Technical details can be referred to our [IEEE IPDPS19 paper][IPDPS19].

:exclamation: Notice that starting at v2.2.0 (including this master branch)

we isolated the executor interface from Taskflow to improve the programming model and performance.

This caused a few breaks in using Cpp-Taskflow.

Please refer to [release-notes](https://cpp-taskflow.github.io/cpp-taskflow/release-2-2-0.html)

for adapting to this new change.

Cpp-Taskflow defines a very expressive API to create task dependency graphs.

Most applications are developed through the following three steps.

Create a taskflow object to build a task dependency graph:

tf::Taskflow taskflow;

A task is a callable object for which [std::invoke][std::invoke] is applicable.

Use the method `emplace` to create a task:

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

You can add dependency links between tasks to enforce one task run after another.

The dependency links must be specified in a

[Directed Acyclic Graph (DAG)](https://en.wikipedia.org/wiki/Directed_acyclic_graph).

The handle `Task` supports different methods for you to describe task dependencies.

**Precede**: Adding a preceding link forces one task to run before another.

A.precede(B); // A runs before B.

**Gather**: Adding a gathering link forces one task to run after another.

A.gather(B); // A runs after B

To execute a taskflow, you need to create an *executor*.

An executor manages a set of worker threads to execute a taskflow

through an efficient *work-stealing* algorithm.

tf::Executor executor;

The executor provides a rich set of methods to run a taskflow.

You can run a taskflow one or multiple times, or until a stopping criteria is met.

These methods are non-blocking and all return a [std::shared_future][std::shared_future]

to let you query the execution status.

```cpp

executor.run(taskflow); // run the taskflow once

executor.run(taskflow, [](){ std::cout << "done 1 run\n"; } ); // run once with a callback

executor.run_n(taskflow, 4); // run four times

executor.run_n(taskflow, 4, [](){ std::cout << "done 4 runs\n"; }); // run 4 times with a callback

// run n times until the predicate becomes true

executor.run_until(taskflow, [counter=4](){ return --counter == 0; } );

// run n times until the predicate becomes true and invoke the callback on completion

executor.run_until(taskflow, [counter=4](){ return --counter == 0; },

[](){ std::cout << "Execution finishes\n"; } );

Notice that executor does not own any taskflow.

It is your responsibility to keep a taskflow alive during its execution,

or it can result in undefined behavior.

In most applications, you need only one executor to run multiple taskflows

each representing a specific part of your parallel decomposition.

Another powerful feature of Taskflow is *dynamic* tasking.

Dynamic tasks are those created during the execution of a taskflow.

These tasks are spawned by a parent task and are grouped together to a *subflow* graph.

The example below demonstrates how to create a subflow

that spawns three tasks at runtime.

<img align="right" src="image/subflow_join.png" width="30%">

This guarantees a subflow graph to finish before the successors of

its parent node.

You can disable this feature by calling `subflow.detach()`.

For example, detaching the above subflow will result in the following execution flow:

<img align="right" src="image/subflow_detach.png" width="35%">

Cpp-Taskflow has an unified interface for static and dynamic tasking.

To create a subflow for dynamic tasking,

emplace a callable with one argument of type `tf::SubflowBuilder`.

tf::Task A = tf.emplace([] (tf::SubflowBuilder& subflow) {});

A subflow builder is a lightweight object that allows you to create

arbitrary dependency graphs at runtime.

All graph building methods defined in taskflow

can be used in the subflow builder.

tf::Task A = tf.emplace([] (tf::SubflowBuilder& subflow) {

});

A subflow can be nested or recursive. You can create another subflow from

the execution of a subflow and so on.

<img align="right" src="image/nested_subflow.png" width="25%">

}); // subflow starts to run after the callable scope

Detaching or joining a subflow has different meaning in the completion status of

its parent node.

In a joined subflow,

the completion of its parent node is defined as when all tasks

inside the subflow (possibly nested) finish.

f1_module_task.precede(f2C);

Run the program and inspect whether dependencies are expressed in the right way.

);

The method `gather` lets you add a preceding link from a task to self.

<img align="right" width="30%" src="image/gather.png">

The constructor of tf::Executor takes an unsigned integer to

initialize the executor with `N` worker threads.

tf::Executor executor(8); // create an executor of 8 worker threads

The first run finishes before the second run, and the second run finishes before the third run.

While Cpp-Taskflow enables the expression of very complex task dependency graph that might contain

thousands of task nodes and links, there are a few amateur pitfalls and mistakes to be aware of.

+ Having a cycle in a graph may result in running forever

+ Destructing a taskflow while it is running in one execution results in undefined behavior

+ Trying to modify a running task can result in undefined behavior

Cpp-Taskflow is known to work on Linux distributions, MAC OSX, and Microsoft Visual Studio.

Please [let me know][email me] if you found any issues in a particular platform.