namespace tf {

/** @page ComposableTasking Composable Tasking

Composition is a key to improve the programmability of a complex workflow.
This chapter describes how to create a large parallel graph through composition of modular and reusable blocks that are easier to optimize.

@tableofcontents

@section ComposeATaskflow Compose a Taskflow

A powerful feature of %Taskflow is its @em composable interface.
You can break down a large parallel workload into smaller pieces
each designed to run a specific task dependency graph.
This largely facilitates the @em modularity of writing a parallel task program.

@code{.cpp}
// f1 has three independent tasks
tf::Taskflow f1;
f1.name("F1");
tf::Task f1A = f1.emplace([&](){ std::cout << "F1 TaskA\n"; });
tf::Task f1B = f1.emplace([&](){ std::cout << "F1 TaskB\n"; });
tf::Task f1C = f1.emplace([&](){ std::cout << "F1 TaskC\n"; });

f1A.name("f1A");
f1B.name("f1B");
f1C.name("f1C");
f1A.precede(f1C);
f1B.precede(f1C);

// f2A ---
//        |----> f2C ----> f1_module_task ----> f2D
// f2B --- 
tf::Taskflow f2;
f2.name("F2");
tf::Task f2A = f2.emplace([&](){ std::cout << "  F2 TaskA\n"; });
tf::Task f2B = f2.emplace([&](){ std::cout << "  F2 TaskB\n"; });
tf::Task f2C = f2.emplace([&](){ std::cout << "  F2 TaskC\n"; });
tf::Task f2D = f2.emplace([&](){ std::cout << "  F2 TaskD\n"; });

f2A.name("f2A");
f2B.name("f2B");
f2C.name("f2C");
f2D.name("f2D");

f2A.precede(f2C);
f2B.precede(f2C);

tf::Task f1_module_task = f2.composed_of(f1).name("module");
f2C.precede(f1_module_task);
f1_module_task.precede(f2D);

f2.dump(std::cout);
@endcode

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

The above example first constructs a taskflow consisting of three tasks, `f1A`, `f1B`, and `f1C`, 
where `f1A` and `f1B` execute before `f1C`. 
It then creates a second taskflow with four tasks, `f2A`, `f2B`, `f2C`, and `f2D`. 
The first taskflow is encapsulated as a module task using Taskflow::composed_of, 
allowing it to be embedded within the second taskflow. 
Dependencies are then established so that `f2C` must complete before the module task begins, 
and the module task must finish before `f2D` executes, 
thereby integrating the two taskflows into a single execution graph with well-defined ordering constraints.

@section CreateAModuleTaskFromATaskflow Create a Module Task from a Taskflow

The task created from Taskflow::composed_of is a @em module task
that runs on a pre-defined taskflow.
A module task does not own the taskflow but maintains a soft 
mapping to the taskflow.
You can create multiple module tasks from the same taskflow
but only one module task can run at one time.
For example, the following composition is valid. 
Even though the two module tasks @c module1 and @c module2 refer to the same taskflow @c F1,
the dependency link prevents @c F1 from multiple executions at the same time.

@dotfile images/composition_static_2.dot

However, the following composition is @em invalid.
Both module tasks refer to the same taskflow. They can not run at the same time because
they are associated with the same graph.

@dotfile images/composition_static_invalid.dot

@section CreateACustomComposableGraph Create a Custom Composable Graph

%Taskflow allows you to create a custom graph object that can participate in
the scheduling using composition.
To become a module task,
your class `T` must define the method `T::graph()` that returns a reference to the tf::Graph object
managed by `T`.
The following example defines a custom graph object that can be assembled in a taskflow
through composition:

@code{.cpp}
 1: struct CustomGraph {
 2:   tf::Graph graph;
 3:   CustomGraph() {
 4:     tf::FlowBuilder builder(graph);  // inherit all task builders in tf::Taskflow
 5:     tf::Task task = builder.emplace([](){
 6:       std::cout << "a task\n";  // static task
 7:     });
 8:   }
 9:   // returns a reference to the graph for taskflow composition
10:   Graph& graph() { return graph; }
11: };
12:
13: CustomGraph obj;
14: tf::Task comp = taskflow.composed_of(obj);
@endcode

The above code defines a custom graph that can participate in taskflow composition. 
The graph object is represented using tf::Graph, and its constructor builds the internal task graph 
through tf::FlowBuilder. 
To support composition, the graph implements the required interface method (`Graph& graph()`)
that exposes its internal structure to the %Taskflow runtime. 
With this interface in place, the custom graph can then be instantiated as a module task within a larger taskflow, enabling it to be seamlessly composed and scheduled alongside other tasks.

@attention
Users are responsible for ensuring the given target remains valid throughout its execution.
The executor does not assume ownership of the target object.


*/

}







