namespace tf {

/** @page StaticTasking Static Tasking

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.

@tableofcontents

@section CreateATaskDependencyGraph Create a Task Dependency Graph

A task in %Taskflow is a @em callable object for which the operation @std_invoke is applicable.
It can be either 
a functor, a lambda expression, a bind expression, or a class objects with @c operator() overloaded.
All tasks are created from tf::Taskflow, the class that manages a task dependency graph.
%Taskflow provides two methods, tf::Taskflow::placeholder and tf::Taskflow::emplace to create a task.

@code{.cpp}
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: );
@endcode

Debrief:
@li Line 1 creates a taskflow object, or a @em graph
@li Line 2 creates a placeholder task without work (i.e., callable)
@li Line 3 creates a task from a given callable object and returns a task handle
@li Lines 5-9 create three tasks in one call using C++ structured binding coupled with std::tuple

Each time you create a task, 
the taskflow object creates a node in the task graph
and returns a task handle of type tf::Task.
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.

@code{.cpp}
 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
@endcode

Debrief:
@li Line 1 creates a taskflow object
@li Lines 2-3 create two tasks A and B
@li Lines 5-6 assign a name and a work to task A, and add a precedence link to task B
@li Line 7 adds a dependency link from A to B
@li Lines 9-14 dump the task attributes 

%Taskflow uses general-purpose polymorphic function wrapper, std::function,
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:

@code{.cpp}
taskflow.emplace([ptr=std::make_unique<int>(1)](){
  std::cout << "captured unique pointer is not copyable";
});
@endcode


@section VisualizeATaskDependencyGraph Visualize a Task Dependency Graph

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>.

@code{.cpp}
 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: }
@endcode

Debrief:
@li Line 5 creates a taskflow object
@li Lines 8-11 create four tasks
@li Lines 14-17 add four task dependencies
@li Line 19 dumps the taskflow in the DOT format through standard output

<!-- @image html images/simple.svg width=40% -->
@dotfile images/simple.dot


@section ModifyTaskAttributes Modify Task Attributes

This example demonstrates how to modify a task's attributes using methods defined in
the task handler.

@code{.cpp}
 1: #include <taskflow/taskflow.hpp>
 2:
 3: int main() {
 4:
 5:   tf::Taskflow taskflow;
 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: }
@endcode

The output of this program looks like the following:

@code{.sh}
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";
}
@endcode

Debrief:
@li Line 5 creates a taskflow object
@li Lines 7-10 create two placeholder tasks with no works and stores the corresponding task handles in a vector
@li Lines 12-13 name the two tasks with human-readable strings 
@li Line 14 adds a dependency link from the first task to the second task
@li Lines 16-20 print out the name of each task, the number of dependents, and the number of successors
@li Line 22 dumps the task dependency graph to a @GraphVizOnline format (dot)
@li Lines 24-25 assign a new target to each task

You can change the name and work of a task at anytime before running the graph.
The later assignment overwrites the previous values.

@section TraverseAdjacentTasks Traverse Adjacent Tasks

You can iterate the successor list and the dependent list of a task by using tf::Task::for_each_successor
and tf::Task::for_each_dependent, respectively.
Each method takes a lambda and applies it to a successor or a dependent being traversed.

@code{.cpp}
// 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';
});
@endcode

@section AttachUserDataToATask Attach User Data to a Task

You can attach custom data to a task using tf::Task::data(void*)
and access it using tf::Task::data().
Each node in a taskflow is associated with a C-styled data pointer
(i.e., `void*`) 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.

@code{.cpp}
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; 
    });
@endcode

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.

@attention
It is your responsibility to ensure that the attached data stay alive
during the execution of its task.


@section UnderstandTheLifetimeOfATask Understand the Lifetime of a Task

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.

@attention
It is your responsibility to keep tasks and graph alive during their execution.


@section MoveATaskflow Move a Taskflow

You can construct or assign a taskflow from a @em moved taskflow.
Moving a taskflow to another will result in transferring the underlying graph 
data structures from one to the other.

@code{.cpp}
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);
@endcode

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 @ref ExecuteATaskflowWithTransferredOwnership for more details.

*/

}