namespace tf {

/** @mainpage A General-purpose Task-parallel Programming System

%Taskflow helps you quickly write high-performance task-parallel programs with high programming productivity.
It is faster, more expressive, fewer lines of code, and easier for drop-in integration
than many of existing task programming libraries.
The source code is available in our @ProjectGitHub.

@tableofcontents

@section ASimpleFirstProgram Start Your First Taskflow Program

The following program (@c simple.cpp) creates a taskflow of four tasks 
@c A, @c B, @c C, and @c D, where @c A runs before @c B and @c C, and @c D
runs after @c B and @c C.
When @c A finishes, @c B and @c C can run in parallel.

@code{.cpp}
#include <taskflow/taskflow.hpp>  // Taskflow is header-only

int main(){
  
  tf::Executor executor;
  tf::Taskflow taskflow;

  auto [A, B, C, D] = taskflow.emplace(  // create four tasks
    [] () { std::cout << "TaskA\n"; },
    [] () { std::cout << "TaskB\n"; },
    [] () { std::cout << "TaskC\n"; },
    [] () { std::cout << "TaskD\n"; } 
  );                                  
                                      
  A.precede(B, C);  // A runs before B and C
  D.succeed(B, C);  // D runs after  B and C
                                      
  executor.run(taskflow).wait(); 

  return 0;
}
@endcode

@dotfile images/simple.dot

%Taskflow is *header-only* and there is no struggle with installation.
To compile the program, clone the %Taskflow project and 
tell the compiler to include the headers under @c taskflow/.

@code{.bash}
~$ git clone https://github.com/taskflow/taskflow.git  # clone it only once
~$ g++ -std=c++20 simple.cpp -I taskflow/ -O2 -pthread -o simple
~$ ./simple
TaskA
TaskC 
TaskB 
TaskD
@endcode

%Taskflow comes with a built-in profiler, @TFProf, 
for you to profile and visualize taskflow programs
in an easy-to-use web-based interface.

@image html images/tfprof_overview.png 

@code{.bash}
# run the program with the environment variable TF_ENABLE_PROFILER enabled
~$ TF_ENABLE_PROFILER=simple.tfp ./simple
# drag the generated tfp file to https://taskflow.github.io/tfprof/
@endcode

@htmlonly
<p>Watch a quick-start video to learn Taskflow programming in just 5 minutes:</p>
<div style="margin:1.5em 0;">
  <div style="position:relative;padding-bottom:56.25%;height:0;overflow:hidden;">
    <iframe
      src="https://www.youtube.com/embed/u4vaY0cjzos"
      title="Taskflow in 5 Minutes"
      style="position:absolute;top:0;left:0;width:100%;height:100%;border:0;"
      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
      allowfullscreen>
    </iframe>
  </div>
</div>
@endhtmlonly

@section QuickStartCreateASubflowGraph Create a Subflow Graph

%Taskflow supports <i>recursive tasking</i> for you to create a subflow
graph from the execution of a task to perform recursive parallelism.
The following program spawns a task dependency graph parented at task @c B.

@code{.cpp}
tf::Task A = taskflow.emplace([](){}).name("A");  
tf::Task C = taskflow.emplace([](){}).name("C");  
tf::Task D = taskflow.emplace([](){}).name("D");  

tf::Task B = taskflow.emplace([] (tf::Subflow& subflow) { // subflow task B
  tf::Task B1 = subflow.emplace([](){}).name("B1");  
  tf::Task B2 = subflow.emplace([](){}).name("B2");  
  tf::Task B3 = subflow.emplace([](){}).name("B3");  
  B3.succeed(B1, B2);  // B3 runs after B1 and B2
}).name("B");

A.precede(B, C);  // A runs before B and C
D.succeed(B, C);  // D runs after  B and C
@endcode

@dotfile images/subflow-join.dot

@section QuickStartIntegrateControlFlowIntoATaskGraph Integrate Control Flow into a Task Graph

%Taskflow supports <i>conditional tasking</i> for you to make rapid 
control-flow decisions across dependent tasks to implement cycles 
and conditions in an @em end-to-end task graph.

@code{.cpp}
tf::Task init = taskflow.emplace([](){}).name("init");
tf::Task stop = taskflow.emplace([](){}).name("stop");

// creates a condition task that returns a random binary
tf::Task cond = taskflow.emplace([](){ return std::rand() % 2; }).name("cond");

// creates a feedback loop {0: cond, 1: stop}
init.precede(cond);
cond.precede(cond, stop);  // moves on to 'cond' on returning 0, or 'stop' on 1
@endcode

@dotfile images/conditional-tasking-1.dot

@section QuickStartComposeTaskGraphs Compose Task Graphs

%Taskflow is composable. You can create large parallel graphs through composition of modular and reusable blocks that are easier to optimize at an individual scope.

@code{.cpp}
tf::Taskflow f1, f2;

// create taskflow f1 of two tasks
tf::Task f1A = f1.emplace([]() { std::cout << "Task f1A\n"; }).name("f1A");
tf::Task f1B = f1.emplace([]() { std::cout << "Task f1B\n"; }).name("f1B");

// create taskflow f2 with one module task composed of f1
tf::Task f2A = f2.emplace([]() { std::cout << "Task f2A\n"; }).name("f2A");
tf::Task f2B = f2.emplace([]() { std::cout << "Task f2B\n"; }).name("f2B");
tf::Task f2C = f2.emplace([]() { std::cout << "Task f2C\n"; }).name("f2C");
tf::Task f1_module_task = f2.composed_of(f1).name("module");

f1_module_task.succeed(f2A, f2B)
              .precede(f2C);
@endcode

@dotfile images/composition.dot

@section QuickStartLaunchAsyncTasks Launch Asynchronous Tasks

%Taskflow supports @em asynchronous tasking.
You can launch tasks asynchronously to dynamically explore task graph parallelism.

@code{.cpp}
tf::Executor executor;

// create asynchronous tasks directly from an executor
std::future<int> future = executor.async([](){ 
  std::cout << "async task returns 1\n";
  return 1;
}); 
executor.silent_async([](){ std::cout << "async task does not return\n"; });

// create asynchronous tasks with dynamic dependencies
tf::AsyncTask A = executor.silent_dependent_async([](){ printf("A\n"); });
tf::AsyncTask B = executor.silent_dependent_async([](){ printf("B\n"); }, A);
tf::AsyncTask C = executor.silent_dependent_async([](){ printf("C\n"); }, A);
tf::AsyncTask D = executor.silent_dependent_async([](){ printf("D\n"); }, B, C);

executor.wait_for_all();
@endcode



@section QuickStartLeverageStandardParallelAlgorithms Leverage Standard Parallel Algorithms

%Taskflow defines algorithms for you to quickly express common parallel patterns
using standard C++ syntaxes, 
such as parallel iterations, parallel reductions, and parallel sort.

@code{.cpp}
// standard parallel CPU algorithms
tf::Task task1 = taskflow.for_each( // assign each element to 100 in parallel
  first, last, [] (auto& i) { i = 100; }    
);
tf::Task task2 = taskflow.reduce(   // reduce a range of items in parallel
  first, last, init, [] (auto a, auto b) { return a + b; }
);
tf::Task task3 = taskflow.sort(     // sort a range of items in parallel
  first, last, [] (auto a, auto b) { return a < b; }
);
@endcode

Additionally, %Taskflow provides composable graph building blocks for you to 
efficiently implement common parallel algorithms, such as parallel pipeline.

@code{.cpp}
// create a pipeline to propagate five tokens through three serial stages
tf::Pipeline pl(num_lines,
  tf::Pipe{tf::PipeType::SERIAL, [](tf::Pipeflow& pf) {
    if(pf.token() == 5) {
      pf.stop();
    }
  }},
  tf::Pipe{tf::PipeType::SERIAL, [](tf::Pipeflow& pf) {
    printf("stage 2: input buffer[%zu] = %d\n", pf.line(), buffer[pf.line()]);
  }},
  tf::Pipe{tf::PipeType::SERIAL, [](tf::Pipeflow& pf) {
    printf("stage 3: input buffer[%zu] = %d\n", pf.line(), buffer[pf.line()]);
  }}
);
taskflow.composed_of(pl)
executor.run(taskflow).wait();
@endcode

@section QuickStartRunATaskflowThroughAnExecution Run a Taskflow through an Executor

The executor provides several @em thread-safe methods to run a taskflow. 
You can run a taskflow once, multiple times, or until a stopping criteria is met. 
These methods are non-blocking with a @c tf::Future<void> return 
to let you query the execution status. 

@code{.cpp}
// runs the taskflow once
tf::Future<void> run_once = executor.run(taskflow); 

// wait on this run to finish
run_once.get();

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

// runs the taskflow five times
executor.run_until(taskflow, [counter=5](){ return --counter == 0; });

// blocks the executor until all submitted taskflows complete
executor.wait_for_all();
@endcode

@section QuickStartOffloadTasksToGPU Offload Tasks to a GPU

%Taskflow supports GPU tasking for you to accelerate a wide range of scientific computing applications by harnessing the power of CPU-GPU collaborative computing using Nvidia CUDA %Graph.

@code{.cpp}
__global__ void saxpy(int n, float a, float *x, float *y) {
  int i = blockIdx.x*blockDim.x + threadIdx.x;
  if (i < n) {
    y[i] = a*x[i] + y[i];
  }
}
// create a CUDA Graph task
tf::Task cudaflow = taskflow.emplace([&]() {
  tf::cudaGraph cg;
  tf::cudaTask h2d_x = cg.copy(dx, hx.data(), N);
  tf::cudaTask h2d_y = cg.copy(dy, hy.data(), N);
  tf::cudaTask d2h_x = cg.copy(hx.data(), dx, N);
  tf::cudaTask d2h_y = cg.copy(hy.data(), dy, N);
  tf::cudaTask saxpy = cg.kernel((N+255)/256, 256, 0, saxpy, N, 2.0f, dx, dy);
  saxpy.succeed(h2d_x, h2d_y)
       .precede(d2h_x, d2h_y);
  
  // instantiate an executable CUDA graph and run it through a stream
  tf::cudaGraphExec exec(cg);
  tf::cudaStream stream;
  stream.run(exec).synchronize();
}).name("CUDA Graph Task");
@endcode

@dotfile images/saxpy_1_cudaflow.dot

@section QuickStartVisualizeATaskflow Visualize Taskflow Graphs

You can dump a taskflow graph to a DOT format and visualize it
using a number of free GraphViz tools such as @GraphVizOnline.


@code{.cpp}
tf::Taskflow taskflow;

tf::Task A = taskflow.emplace([](){}).name("A");
tf::Task B = taskflow.emplace([](){}).name("B");
tf::Task C = taskflow.emplace([](){}).name("C");
tf::Task D = taskflow.emplace([](){}).name("D");
tf::Task E = taskflow.emplace([](){}).name("E");
A.precede(B, C, E);
C.precede(D);
B.precede(D, E);

// dump the graph to a DOT file through std::cout
taskflow.dump(std::cout); 
@endcode

@dotfile images/graphviz.dot

@section SupportedCompilers Supported Compilers

To use %Taskflow v4.0.0, you need a compiler that supports C++20:

@li GNU C++ Compiler at least v11.0 with -std=c++20
@li Clang C++ Compiler at least v12.0 with -std=c++20
@li Microsoft Visual Studio at least v19.29 (VS 2019) with /std:c++20
@li Apple Clang (Xcode) at least v13.0 with -std=c++20
@li NVIDIA CUDA Toolkit and Compiler (nvcc) at least v12.0 with host compiler supporting C++20
@li Intel oneAPI DPC++/C++ Compiler at least v2022.0 with -std=c++20

%Taskflow works on Linux, Windows, and Mac OS X.

@section QuickStartGetInvolved Get Involved

Visit our @ProjectWebsite and @ShowcasePresentation 
to learn more about %Taskflow. To get involved:

  + See release notes at @ref Releases
  + Read the step-by-step tutorial at @ref Cookbook
  + Submit an issue at @IssueTracker
  + Learn more about our technical details at @ref References
  + Watch our @CppCon20Talk and @MUCpp20Talk

We are committed to support trustworthy developments for 
both academic and industrial research projects in parallel 
and heterogeneous computing. 
If you are using %Taskflow, please cite the following paper we published at 2022 IEEE TPDS:

+ Tsung-Wei Huang, Dian-Lun Lin, Chun-Xun Lin, and Yibo Lin, &quot;[Taskflow: A Lightweight Parallel and Heterogeneous Task Graph Computing System](https://tsung-wei-huang.github.io/papers/tpds21-taskflow.pdf),&quot; <i>IEEE Transactions on Parallel and Distributed Systems (TPDS)</i>, vol. 33, no. 6, pp. 1303-1320, June 2022

More importantly, we appreciate all %Taskflow @ref contributors and 
the following organizations for sponsoring the %Taskflow project!

<table class="sponsor-table">
<tr>
  <td>@image html "images/utah-ece-logo.png"</td>
  <td>@image html "images/nsf.png"</td>
  <td>@image html "images/darpa.png"</td>
  <td>@image html "images/NumFocus.png"</td>
</tr>
<tr>
  <td>@image html "images/nvidia-logo.png"</td>
  <td>@image html "images/uw-madison-ece-logo.png"</td>
  <td></td>
  <td></td>
</tr>
</table>


@section License License

%Taskflow is open-source the under permissive MIT license.
You are completely free to use, modify, and redistribute any work 
on top of %Taskflow.
The source code is available in @ProjectGitHub and is actively
maintained by @twhuang and his research group at the University of Wisconsin at Madison.

*/

}
