namespace tf {

/** @page FAQ Frequently Asked Questions

This page summarizes a list of frequently asked questions about %Taskflow.
If you cannot find a solution here, please post an issue at
<a href="https://github.com/taskflow/taskflow/issues">here</a>.

@tableofcontents

@section GeneralQuestions General Questions

@subsection GeneralQuestion1 Q1: What's the goal of Taskflow?

%Taskflow aims to help C++ developers quickly implement efficient 
parallel decomposition strategies using task-based approaches.

@subsection GeneralQuestion2 Q2: How do I use Taskflow in my projects?

%Taskflow is a header-only library with zero dependencies. 
The only thing you need is a C++17 compiler.
To use %Taskflow, simply drop the folder @c taskflow/
to your project and include taskflow.hpp.

@subsection GeneralQuestion3 Q3: What is the difference between static tasking and dynamic tasking?

Static tasking refers to those tasks created before execution,
while dynamic tasking refers to those tasks created during the execution of static tasks
or dynamic tasks (nested).
Dynamic tasks created by the same task node are grouped together to a subflow.

@subsection GeneralQuestion4 Q4: How many tasks can Taskflow handle?

Benchmarks showed %Taskflow can efficiently handle millions or billions of tasks 
(both large and small tasks) on a machine with up to 64 CPUs.

@subsection GeneralQuestion5 Q5: What is the weird hex value, like 0x7fc39d402ab0, in the dumped graph?

The hex value represents the memory address of the task.
Each task has a method tf::Task::name(const std::string&) for user to assign a human readable string
to ease the debugging process. If a task is not assigned a name or is an internal node,
its address value in the memory is used instead.

@subsection GeneralQuestion6 Q6: Does Taskflow have backward compatibility with C++03/98/11/14?

Unfortunately, %Taskflow is heavily relying on modern C++17's features/idoms/STL 
and it is very difficult to provide a version that compiles under older C++ versions.

@subsection GeneralQuestion7 Q7: How does Taskflow schedule tasks?

%Taskflow implemented a very efficient 
<a href="https://en.wikipedia.org/wiki/Work_stealing">work-stealing scheduler</a> 
to execute task dependency graphs.
The source code is available at @c taskflow/core/executor.hpp.

@subsection GeneralQuestion8 Q8: What is the overhead of taskflow?

Creating a taskflow has certain overhead. For example, creating a task and a dependency 
takes about 61 and 14 nanoseconds in our system (Intel 4-core CPU at 2.00GHz).
The time is amortized over 1M operations, since we have implemented an object pool 
to recycle tasks for minimal overhead.

@subsection GeneralQuestion9 Q9: How does it compare to existing task programming systems?

There is a large amount of work on programming systems (e.g., StarPU, Intel TBB, OpenMP, PaRSEC, Kokkos, HPX) in the interest of simplifying the 
programming complexity of parallel and heterogeneous computing. 
Each of these systems has its own pros and cons and deserves a reason to exist.
However, they do have some problems, particularly from the standpoint of ease of use, 
static control flow, and scheduling efficiency.
%Taskflow addresses these limitations through a simple, expressive, and transparent
graph programming model.

@subsection GeneralQuestion10 Q10: Do you try to simplify the GPU kernel programming?

No, we do not develop new programming models to simplify the kernel programming.
The rationale is simple: Writing efficient kernels requires domain-specific knowledge 
and developers often require direct access to the native GPU programming interface.
High-level kernel programming models or abstractions all come with restricted applicability.
Despite non-trivial kernel programming, we believe what makes heterogeneous computing difficult
are surrounding tasks.
A mistake made by task scheduling can outweigh all speed-up benefits from a highly optimized kernel.
Therefore, %Taskflow focuses on heterogeneous tasking 
that affects the overall system performance to a large extent.

@subsection GeneralQuestion11 Q11: Do you have any real use cases?

We have applied %Taskflow to solve many realistic workloads and demonstrated promising
performance scalability and programming productivity. Please refer to @ref usecases
and @ref References.

@subsection GeneralQuestion12 Q12: Who is the Principal Investigator of Taskflow I can talk to?

Please visit this <a href="https://taskflow.github.io/#tag_contact">page</a> or email 
the investigator @twhuang.

@subsection GeneralQuestion13 Q13: Who are developing and maintaining Taskflow?

%Taskflow is in active development with core functionalities contributed 
by an academic group at the University of Utah, led by @twhuang.
While coming out of an academic lab, %Taskflow aims to be industrial-strength
and is committed to long-term support.

@subsection GeneralQuestion14 Q14: Is Taskflow just an another API or model?

OK, let me ask this first: <i>Is your new car just another vehicle? Or, is your new home just another place to live?</i> 

The answer to this question is the question itself. As technology advances,
we can always find new ways to solve computational problems 
and achieve new performance milestones that were previously out-of-reach.

@subsection GeneralQuestion15 Q15: How can I contribute?

New contributors are always welcome! Please visit @ref Contributing.

@subsection GeneralQuestion16 Q16: Does Taskflow support pipeline parallelism?

Yes, %Taskflow has a specialized programming model to create a 
pipeline scheduling framework. Please visit @ref TaskParallelPipeline
and @ref DataParallelPipeline.


----


@section ProgrammingQuestions Programming Questions

@subsection ProgrammingQuestions1 Q1: What is the difference between Taskflow threads and workers?

The master thread owns the thread pool and can spawn workers to run tasks 
or shutdown the pool. 
Giving taskflow @c N threads means using @c N threads to do the works, 
and there is a total of @c N+1 threads (including the master thread) in the program.
Please refer to @ref CreateAnExecutor for more details.

@subsection ProgrammingQuestions2 Q2: What is the Lifetime of a Task and a Graph?

The lifetime of a task sticks with its parent graph. 
A task is not destroyed until its parent graph is destroyed.
Please refer to @ref UnderstandTheLifetimeOfATask for more details.

@subsection ProgrammingQuestions3 Q3: Is taskflow thread-safe?

No, the taskflow object is not thread-safe. Multiple threads cannot create tasks from the same taskflow at the same time.

@subsection ProgrammingQuestions4 Q4: Is executor thread-safe?

Yes, the executor object is thread-safe. 
You can have multiple threads submit different taskflows to the same executor.

@subsection ProgrammingQuestions5 Q5: My program hangs and never returns after dispatching a taskflow graph. What's wrong?

When the program hangs forever it is very likely your taskflow graph has a cycle or 
not properly conditioned (see @ref ConditionalTasking).
Try the tf::Taskflow::dump method to debug the graph before dispatching your taskflow graph.


@subsection ProgrammingQuestions6 Q6: In the following example where B spawns a joined subflow of three tasks B1, B2, and B3, do they run concurrently with task A?

@dotfile images/subflow-join.dot

No. The subflow is spawned during the execution of @c B, 
and at this point @c A must have finished
because @c A precedes @c B. This gives rise to the fact @c B1 and @c B2 
must run after @c A. 

@subsection ProgrammingQuestions7 Q7: What is the purpose of a condition task?

A condition task lets you perform @em in-task decision making so you can 
integrate control flow into a task graph with end-to-end parallelism
without synchronizing or partitioning your parallelism across conditionals.

@subsection ProgrammingQuestions8 Q8: Is the program master thread involved in running tasks?

No, the program master thread is not involved in running taskflows. 
The executor keeps a set of private worker threads spawned upon 
construction time to run tasks.

@subsection ProgrammingQuestions9 Q9: Are there any limits on the branches of conditional tasking?

No, as long as the return value points to a valid successors, 
your conditional tasking is valid.

@subsection ProgrammingQuestions10 Q10: Why does Taskflow program GPU in a task graph?

We ask users to describe a GPU workload in a task graph and execute it
in a second moment. 
This organization minimizes kernels launch overhead and 
allows the GPU runtime (e.g., CUDA) to optimize the whole workflow.

@subsection ProgrammingQuestions11 Q11: Can I limit the concurrency in certain sections of tasks?

Yes, %Taskflow provides a lightweight mechanism, tf::Semaphore, for you to
limit the maximum concurrency (i.e., the number of workers) in a section of tasks.
Please refer to @ref LimitTheMaximumConcurrency.

@subsection ProgrammingQuestions12 Q12: How can I attach custom data to a task and access it?

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.
Please refer to @ref AttachUserDataToATask.

*/

}





