namespace tf {

/** @page ConditionalTasking Conditional Tasking

One of the most powerful features that distinguishes %Taskflow from other systems is its support for <i>conditional tasking</i>, also known as the <i>control taskflow programming model</i> (CTFG). CTFG allows you to embed control flow directly within a taskflow graph, enabling tasks to make decisions dynamically during execution. 
This mechanism supports advanced in-graph control flow patterns, such as dynamic branching, loops, and conditionals—that are typically difficult or impossible to express in traditional task graph models.

@tableofcontents

@section CreateAConditionTask Create a Condition Task

A condition task returns an integer index indicating which successor task to execute next. 
The index corresponds to the position of the successor in the order it was added during task construction.
The following example creates an if-else block using a condition task.

@code{.cpp}
tf::Taskflow taskflow;
auto [init, cond, yes, no] = taskflow.emplace(
 [] () { },
 [] () { return 0; },
 [] () { std::cout << "yes\n"; },
 [] () { std::cout << "no\n"; }
);
cond.succeed(init)
    .precede(yes, no);  // executes yes if cond returns 0
                        // executes no  if cond returns 1
@endcode

@dotfile images/conditional-tasking-if-else.dot

The condition task @c cond is connected to two successor tasks, @c yes and @c no, via @c precede(yes, no).
When @c cond returns @c 0, the execution moves on to @c yes.
When @c cond returns @c 1, the execution moves on to @c no.

@note
It is your responsibility to ensure that the return value of a condition task corresponds to a valid successor.
If the returned index is out of range, the executor will not schedule any successor tasks.


A condition task can form a cycle to express @em iterative control flow.
The example below demonstrates a simple yet commonly used feedback loop implemented using a condition task that returns a random binary value.
If the return value from @c cond is @c 0, the task loops back to itself; otherwise, it proceeds to @c stop.

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

tf::Task init = taskflow.emplace([](){}).name("init");
tf::Task stop = taskflow.emplace([](){}).name("stop");
// creates a condition task that returns 0 or 1
tf::Task cond = taskflow.emplace([](){
  std::cout << "flipping a coin\n";
  return std::rand() % 2;
}).name("cond");
// creates a feedback loop {0: cond, 1: stop}
init.precede(cond);
cond.precede(cond, stop);  // returns 0 to 'cond' or 1 to 'stop'
executor.run(taskflow).wait();
@endcode

<!-- @image html images/conditional-tasking-1.svg width=45% -->
@dotfile images/conditional-tasking-1.dot

Creating a taskflow with complex control flow often requires only a few lines of code to implement.
Different control flow paths can execute in parallel, making it easy to express both logic and concurrency.
The code below creates a taskflow with three condition tasks to demonstrate this capability:

@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");
tf::Task F = taskflow.emplace([](){}).name("F");
tf::Task G = taskflow.emplace([](){}).name("G");
tf::Task H = taskflow.emplace([](){}).name("H");
tf::Task I = taskflow.emplace([](){}).name("I");
tf::Task K = taskflow.emplace([](){}).name("K");
tf::Task L = taskflow.emplace([](){}).name("L");
tf::Task M = taskflow.emplace([](){}).name("M");
tf::Task cond_1 = taskflow.emplace([](){ return std::rand()%2; }).name("cond_1");
tf::Task cond_2 = taskflow.emplace([](){ return std::rand()%2; }).name("cond_2");
tf::Task cond_3 = taskflow.emplace([](){ return std::rand()%2; }).name("cond_3");

A.precede(B, F);
B.precede(C);
C.precede(D);
D.precede(cond_1);
E.precede(K);
F.precede(cond_2);
H.precede(I);
I.precede(cond_3);
L.precede(M);

cond_1.precede(B, E);       // return 0 to 'B' or 1 to 'E'
cond_2.precede(G, H);       // return 0 to 'G' or 1 to 'H'
cond_3.precede(cond_3, L);  // return 0 to 'cond_3' or 1 to 'L'

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

The above code creates three condition tasks to implement three different control-flow tasks:
  1. A condition task @c cond_1 that loops back 
to @c B on returning @c 0, or proceeds to @c E on returning @c 1,
  2. A condition task @c cond_2 that goes to @c G on returning @c 0,
or @c H on returning @c 1,
  3. A condition task @c cond_3 that loops back to itself on returning @c 0, 
or proceeds to @c L on returning @c 1

<!-- @image html images/conditional-tasking-2.svg width=100% -->
@dotfile images/conditional-tasking-2.dot

In this particular example, we can clearly see the advantage of CTFG: the execution of @c cond_1 can overlap with @c cond_2 or @c cond_3, enabling greater concurrency in control-driven workloads.
Unlike traditional task graph models that require static structure or external orchestration to handle control flow, CTFG allows tasks to make decisions dynamically and continue execution without global synchronization barriers.
This design leads to better parallelism, reduced overhead, and more expressive task graphs, especially in workloads with branching or iterative control flows.


@section TaskSchedulingPolicy Understand our Task-level Scheduling

In order to understand how an executor schedules condition tasks,
we define two dependency types,
<em>strong dependency</em> and <em>weak dependency</em>.
A strong dependency is a preceding link from one non-condition task to another task.
A weak dependency is a preceding link from one condition task to another task.
The number of dependencies of a task is the sum of its strong dependencies and weak dependencies.
The table below lists the number of strong dependencies and weak dependencies
of each task in the previous example:

<div align="center">
| task   | strong dependency | weak dependency | dependencies |
| :-:    | :-:               | :-:             |              |
| A      | 0                 | 0               | 0            |
| B      | 1                 | 1               | 2            |
| C      | 1                 | 0               | 1            |
| D      | 1                 | 0               | 1            |
| E      | 0                 | 1               | 1            |
| F      | 1                 | 0               | 1            |
| G      | 0                 | 1               | 1            |
| H      | 0                 | 1               | 1            |
| I      | 1                 | 0               | 1            |
| K      | 1                 | 0               | 1            |
| L      | 0                 | 1               | 1            | 
| M      | 1                 | 0               | 1            |
| cond_1 | 1                 | 0               | 1            |
| cond_2 | 1                 | 0               | 1            |
| cond_3 | 1                 | 1               | 2            |
</div>

You can query the number of strong dependencies,
the number of weak dependencies,
and the number of dependencies of a task.

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

tf::Task task = taskflow.emplace([](){});

// ... add more tasks and preceding links
std::cout << task.num_predecessors() << '\n';
std::cout << task.num_strong_dependencies() << '\n'; 
std::cout << task.num_weak_dependencies() << '\n';
@endcode

When you submit a task to an executor,
the scheduler starts with tasks of <em>zero dependencies</em>
(both zero strong and weak dependencies)
and continues to execute successive tasks whenever 
their <em>strong dependencies</em> are met.
However, the scheduler skips this rule when executing a condition task
and jumps directly to its successors indexed by the return value.

<!-- @image html images/conditional-tasking-rules.svg width=100% -->
@dotfile images/task_level_scheduling.dot

Each task has an @em atomic join counter to keep track of strong dependencies
that are met at runtime.
When a task completes,
the join counter is restored to the task's strong dependency number 
in the graph, such that the subsequent execution can reuse the counter again.

@subsection TaskLevelSchedulingExample Example

Let's take a look at an example to understand how task-level scheduling
works. Suppose we have the following taskflow of one condition task @c cond
that forms a loop to itself on returning @c 0 and moves on to @c stop on
returning @c 1:

@dotfile images/conditional-tasking-1.dot

The scheduler starts with @c init task because it has no dependencies 
(both strong and weak dependencies).
Then, the scheduler moves on to the condition task @c cond.
If @c cond returns @c 0, the scheduler enqueues @c cond and runs it again.
If @c cond returns @c 1, the scheduler enqueues @c stop and then moves on.


@section AvoidCommonPitfalls Avoid Common Pitfalls

Condition tasks are powerful but require careful graph construction.
The following pitfalls are the most common sources of bugs when using
conditional tasking, ranging from silent deadlocks to non-deterministic
task races.

@subsection PitfallNoSourceTask Pitfall 1: No Source Task

Every taskflow must have at least one task with zero dependencies for the
scheduler to start with.
When a condition task forms a cycle, it is easy to accidentally create a
graph where every task has at least one incoming edge, leaving the scheduler
with no entry point.

The figure below shows common pitfalls and their remedies.

<!-- @image html images/conditional-tasking-pitfalls.svg  width=100% -->
@dotfile images/conditional-tasking-pitfalls.dot

In the @c error1 scenario, there is no source task for the scheduler to
start with.
The simplest fix is to add a task @c S with no dependencies that precedes
the rest of the graph, giving the scheduler an unambiguous entry point.

@subsection PitfallTaskRace Pitfall 2: Task Race

A task race occurs when the same task can be scheduled more than once
simultaneously through different paths.
This typically happens when a task has both a strong dependency from a
regular task and a weak dependency from a condition task.

In the @c error2 scenario, task @c D can be scheduled twice: once by @c E
through its strong dependency, and once by @c C through its weak dependency
(when @c C returns @c 1).
If both paths activate @c D at the same time, @c D runs concurrently with
itself, which is undefined behavior.
The fix is to insert an auxiliary task @c D-aux between the two paths so
that @c D always has exactly one active predecessor at a time.

In the risky scenario, task @c X may be raced by @c M and @c P if @c M
returns @c 0 and @c P returns @c 1 simultaneously, triggering @c X from
two different condition tasks at once.
Whenever a task sits at the junction of multiple condition task outputs,
carefully check whether those condition tasks can fire concurrently.

@subsection PitfallDeadlock Pitfall 3: Deadlock from Strong Back-edge

A deadlock occurs when a condition task loops back to a task via a strong
dependency rather than a weak one.
Because the scheduler only moves a task to the ready queue when all its
@em strong dependencies are satisfied, a loop that creates a strong
back-edge will permanently block: the loop body waits for the condition
task to complete, but the condition task can never re-run because the loop
body has not been executed yet.

The wrong while-loop implementation at @ref ImplementWhileLoopControlFlow
is a concrete example of this pitfall.
When the body task @c i++ directly precedes the loop condition task @c cond
with @c body.precede(cond), it creates a strong dependency.
After @c init runs and decrements @c cond's strong dependency count by one,
@c cond still waits for @c i++ to complete before it can run.
But @c i++ only runs after @c cond returns @c 0, so neither task can
proceed and the graph deadlocks.
The correct fix is to introduce a dedicated back-edge condition task @c back
that returns @c 0 unconditionally to @c cond, creating a weak dependency
instead.

@note
When in doubt, use tf::Taskflow::dump to visualize your graph and cross-reference
the strong and weak dependency counts in the table at @ref TaskSchedulingPolicy.
A task that has both strong and weak incoming edges from active paths is a
strong signal that a race or deadlock may be present.

@section ImplementControlFlowGraphs Implement Control-flow Graphs

@subsection ImplementIfElseControlFlow Implement If-Else Control Flow

You can use conditional tasking to implement if-else control flow.
The following example creates a nested if-else control flow diagram that 
executes three condition tasks to check the range of @c i.

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

int i;

// create three condition tasks for nested control flow
auto initi = taskflow.emplace([&](){ i=3; }); 
auto cond1 = taskflow.emplace([&](){ return i>1 ? 1 : 0; }); 
auto cond2 = taskflow.emplace([&](){ return i>2 ? 1 : 0; }); 
auto cond3 = taskflow.emplace([&](){ return i>3 ? 1 : 0; }); 
auto equl1 = taskflow.emplace([&](){ std::cout << "i=1\n"; }); 
auto equl2 = taskflow.emplace([&](){ std::cout << "i=2\n"; }); 
auto equl3 = taskflow.emplace([&](){ std::cout << "i=3\n"; }); 
auto grtr3 = taskflow.emplace([&](){ std::cout << "i>3\n"; }); 

initi.precede(cond1);
cond1.precede(equl1, cond2);  // goes to cond2 if i>1
cond2.precede(equl2, cond3);  // goes to cond3 if i>2
cond3.precede(equl3, grtr3);  // goes to grtr3 if i>3
@endcode

@dotfile images/conditional-tasking-nested-if-else.dot


@subsection ImplementSwitchControlFlow Implement Switch Control Flow

You can use condition tasks to implement @em switch-style control flow.
The following example demonstrates this by creating a switch structure that randomly selects and executes one of three cases using four condition tasks.

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

auto [source, swcond, case1, case2, case3, target] = taskflow.emplace(
  [](){ std::cout << "source\n"; },
  [](){ std::cout << "switch\n"; return rand()%3; },
  [](){ std::cout << "case 1\n"; return 0; },
  [](){ std::cout << "case 2\n"; return 0; },
  [](){ std::cout << "case 3\n"; return 0; },
  [](){ std::cout << "target\n"; }
);

source.precede(swcond);
swcond.precede(case1, case2, case3);
target.succeed(case1, case2, case3);
@endcode

@dotfile images/conditional-tasking-switch.dot

Assuming @c swcond returns 1, the program outputs:

@code{.bash}
source
switch
case 2
target
@endcode

Keep in mind, both switch and case tasks must be described as condition tasks.
The following implementation is a common mistake in which case tasks
are not described as condition tasks.

@code{.cpp}
// wrong implementation of switch control flow using only one condition task
tf::Taskflow taskflow;

auto [source, swcond, case1, case2, case3, target] = taskflow.emplace(
  [](){ std::cout << "source\n"; },
  [](){ std::cout << "switch\n"; return rand()%3; },
  [](){ std::cout << "case 1\n"; },
  [](){ std::cout << "case 2\n"; },
  [](){ std::cout << "case 3\n"; },
  [](){ std::cout << "target\n"; }  // target has three strong dependencies
);

source.precede(swcond);
swcond.precede(case1, case2, case3);
target.succeed(case1, case2, case3);
@endcode

@dotfile images/conditional-tasking-switch-wrong.dot

In this faulty implementation, task @c target has three strong dependencies
but only one of them will be met.
This is because @c swcond is a condition task,
and only one case task will be executed depending on the return of @c swcond.


@subsection ImplementDoWhileLoopControlFlow Implement Do-While-Loop Control Flow

You can use conditional tasking to implement @em do-while-loop control flow.
The following example creates a do-while-loop control flow diagram that 
repeatedly increments variable @c i five times using one condition task.

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

int i;

auto [init, body, cond, done] = taskflow.emplace(
  [&](){ std::cout << "i=0\n"; i=0; },
  [&](){ std::cout << "i++ => i="; i++; },
  [&](){ std::cout << i << '\n'; return i<5 ? 0 : 1; },
  [&](){ std::cout << "done\n"; }
);  

init.precede(body);
body.precede(cond);
cond.precede(body, done);
@endcode

@dotfile images/conditional-tasking-do-while.dot

The program outputs:

@code{.bash}
i=0
i++ => i=1
i++ => i=2
i++ => i=3
i++ => i=4
i++ => i=5
done
@endcode

@subsection ImplementWhileLoopControlFlow Implement While-Loop Control Flow

You can use conditional tasking to implement @em while-loop control flow.
The following example creates a while-loop control flow diagram that 
repeatedly increments variable @c i five times using two condition task.

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

int i;

auto [init, cond, body, back, done] = taskflow.emplace(
  [&](){ std::cout << "i=0\n"; i=0; },
  [&](){ std::cout << "while i<5\n"; return i < 5 ? 0 : 1; },
  [&](){ std::cout << "i++=" << i++ << '\n'; },
  [&](){ std::cout << "back\n"; return 0; },
  [&](){ std::cout << "done\n"; }
);

init.precede(cond);
cond.precede(body, done);
body.precede(back);
back.precede(cond);
@endcode

@dotfile images/conditional-tasking-while.dot

The program outputs:

@code{.bash}
i=0
while i<5
i++=0
back
while i<5
i++=1
back
while i<5
i++=2
back
while i<5
i++=3
back
while i<5
i++=4
back
while i<5
done
@endcode

Notice that, when you implement a while-loop block, you cannot direct 
a dependency from the body task to the loop condition task.
Doing so will introduce a strong dependency between the body task
and the loop condition task, and the loop condition task will never be executed.
The following code shows a common faulty implementation of 
while-loop control flow.

@code{.cpp}
// wrong implementation of while-loop using only one condition task
tf::Taskflow taskflow;

int i;

auto [init, cond, body, done] = taskflow.emplace(
  [&](){ std::cout << "i=0\n"; i=0; },
  [&](){ std::cout << "while i<5\n"; return i < 5 ? 0 : 1; },
  [&](){ std::cout << "i++=" << i++ << '\n'; },
  [&](){ std::cout << "done\n"; }
);

init.precede(cond);
cond.precede(body, done);
body.precede(cond);
@endcode

@dotfile images/conditional-tasking-while-wrong.dot

In the taskflow diagram above,
the scheduler starts with @c init and then decrements the strong dependency of
the loop condition task, <tt>while i<5</tt>. 
After this, there remains one strong dependency, i.e., introduced by
the loop body task, @c i++.
However, task @c i++ will not be executed until the loop condition task returns @c 0,
causing a deadlock.


@section CreateAMultiConditionTask Create a Multi-condition Task

A <i>multi-condition task</i> is a generalized version of conditional tasking.
In some cases, applications need to jump to multiple branches from a parent task.
This can be done by creating a <i>multi-condition task</i> which allows a task
to select one or more successor tasks to execute.
Similar to a condition task, a multi-condition task returns
a vector of integer indices that indicate the successors to execute
when the multi-condition task completes.
The index is defined with respect to the order of successors preceded by
a multi-condition task.
For example, the following code creates a multi-condition task, @c A,
that informs the scheduler to run on its two successors, @c B and @c D.

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

auto A = taskflow.emplace([&]() -> tf::SmallVector<int> { 
  std::cout << "A\n"; 
  return {0, 2};
}).name("A");
auto B = taskflow.emplace([&](){ std::cout << "B\n"; }).name("B");
auto C = taskflow.emplace([&](){ std::cout << "C\n"; }).name("C");
auto D = taskflow.emplace([&](){ std::cout << "D\n"; }).name("D");

A.precede(B, C, D);

executor.run(taskflow).wait();
@endcode

@dotfile images/multi-condition-task-1.dot

@note
The return type of a multi-condition task is tf::SmallVector,
which provides C++ vector-style functionalities but comes with small buffer optimization.


*/

}



