tf::Task class

tf::Task::Task() defaulted

constructs an empty task

An empty task is not associated with any node in a taskflow.

tf::Task::Task(const Task& other)

constructs the task with the copy of the other task

tf::Taskflow taskflow;
tf::Task A = taskflow.emplace([](){ std::cout << "Task A\n"; });
tf::Task B(A);
assert(B == A); // Now, B and A refer to the same underlying node

Task& tf::Task::operator=(const Task& other)

replaces the contents with a copy of the other task

tf::Task A = taskflow.emplace([](){ std::cout << "A\n"; });
tf::Task B;
B = A;  // B now refers to the same node as A

Task& tf::Task::operator=(std::nullptr_t)

replaces the contents with a null pointer

tf::Task A = taskflow.emplace([](){ std::cout << "A\n"; });
A = nullptr;  // A no longer refers to any node

bool tf::Task::operator==(const Task& rhs) const

compares if two tasks are associated with the same taskflow node

tf::Task A = taskflow.emplace([](){ std::cout << "A\n"; });
tf::Task B = A;
assert(A == B);  // A and B refer to the same node

bool tf::Task::operator!=(const Task& rhs) const

compares if two tasks are not associated with the same taskflow node

tf::Task A = taskflow.emplace([](){ std::cout << "A\n"; });
tf::Task B = taskflow.emplace([](){ std::cout << "B\n"; });
assert(A != B);  // A and B refer to different nodes

const std::string& tf::Task::name() const

queries the name of the task

tf::Task task = taskflow.emplace([](){});
task.name("MyTask");
std::cout << "Task name: " << task.name() << std::endl;

size_t tf::Task::num_successors() const

queries the number of successors of the task

tf::Task A = taskflow.emplace([](){});
tf::Task B = taskflow.emplace([](){});
A.precede(B);  // B is a successor of A
std::cout << "A has " << A.num_successors() << " successor(s)." << std::endl;

size_t tf::Task::num_predecessors() const

queries the number of predecessors of the task

tf::Task A = taskflow.emplace([](){});
tf::Task B = taskflow.emplace([](){});
A.precede(B);  // A is a predecessor of B
std::cout << "B has " << B.num_predecessors() << " predecessor(s)." << std::endl;

size_t tf::Task::num_strong_dependencies() const

queries the number of strong dependencies of the task

A strong dependency is a preceding link from one non-condition task to another task. For instance, task cond below has one strong dependency, while tasks yes and no each have one weak dependency.

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

size_t tf::Task::num_weak_dependencies() const

queries the number of weak dependencies of the task

A weak dependency is a preceding link from one condition task to another task. For instance, task cond below has one strong dependency, while tasks yes and no each have one weak dependency.

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

Task& tf::Task::name(const std::string& name)

assigns a name to the task

tf::Task task = taskflow.emplace([](){}).name("foo");
assert(task.name*) == "foo");

template<typename C>

Task& tf::Task::work(C&& callable)

assigns a callable

A tf::Task is polymorphic. Once created, you can reassign it to a different callable of a different task type using tf::Task::work. For example, the code below creates a static task and reworks it to a subflow task:

tf::Task task = taskflow.emplace([](){}).name("static task");
task.work([](tf::Subflow& sf){
  tf::Task stask1 = sf.emplace([](){});
  tf::Task stask2 = sf.emplace([](){});
}).name("subflow task");

template<typename T>

Task& tf::Task::composed_of(T& object)

creates a module task from a taskflow

The example below creates a module task from a taskflow:

task.composed_of(taskflow);

To understand how Taskflow schedules a module task including how to create a schedulable graph, pleas refer to Create a Custom Composable Graph.

template<typename... Ts>

Task& tf::Task::precede(Ts && ... tasks)

adds precedence links from this to other tasks

The example below creates a taskflow of two tasks, where task1 runs before task2.

auto [task1, task2] = taskflow.emplace(
  [](){ std::cout << "task1\n"; },
  [](){ std::cout << "task2\n"; }
);
task1.precede(task2);

template<typename... Ts>

Task& tf::Task::succeed(Ts && ... tasks)

adds precedence links from other tasks to this

The example below creates a taskflow of two tasks, where task1 runs before task2.

auto [task1, task2] = taskflow.emplace(
  [](){ std::cout << "task1\n"; },
  [](){ std::cout << "task2\n"; }
);
task2.succeed(task1);

template<typename... Ts>

Task& tf::Task::remove_predecessors(Ts && ... tasks)

removes predecessor links from other tasks to this

This method removes the dependency links where the given tasks are predecessors of this task (i.e., tasks -> this). It ensures both sides of the dependency are updated to maintain graph consistency.

tf::Task A = taskflow.emplace([](){});
tf::Task B = taskflow.emplace([](){});
tf::Task C = taskflow.emplace([](){});
// create a linear chain of tasks, A->B->C
B.succeed(A)
 .precede(C);
assert(B.num_successors() == 1 && C.num_predecessors() == 1);

// remove C from B's successor list
C.remove_predecessors(B);
assert(B.num_successors() == 0 && C.num_predecessors() == 0);

template<typename... Ts>

Task& tf::Task::remove_successors(Ts && ... tasks)

removes successor links from this to other tasks

This method removes the dependency links where this task is a predecessor of the given tasks (i.e., this -> tasks). It ensures both sides of the dependency are updated to maintain graph consistency.

tf::Task A = taskflow.emplace([](){});
tf::Task B = taskflow.emplace([](){});
tf::Task C = taskflow.emplace([](){});
// create a linear chain of tasks, A->B->C
B.succeed(A)
 .precede(C);
assert(B.num_successors() == 1 && C.num_predecessors() == 1);

// remove C from B's successor list
B.remove_successors(C);
assert(B.num_successors() == 0 && C.num_predecessors() == 0);

Task& tf::Task::release(Semaphore& semaphore)

makes the task release the given semaphore

template<typename I>

Task& tf::Task::release(I first, I last)

makes the task release the given range of semaphores

Task& tf::Task::acquire(Semaphore& semaphore)

makes the task acquire the given semaphore

template<typename I>

Task& tf::Task::acquire(I first, I last)

makes the task acquire the given range of semaphores

Task& tf::Task::data(void* data)

assigns pointer to user data

The following example shows how to attach a user data to a task and retrieve it during the execution of the task.

tf::Executor executor;
tf::Taskflow taskflow("attach data to a task");

int data;  // user data

// create a task and attach it a user data
auto A = taskflow.placeholder();
A.data(&data).work([A](){
  auto d = *static_cast<int*>(A.data());
  std::cout << "data is " << d << std::endl;
});

// run the taskflow iteratively with changing data
for(data = 0; data<10; data++){
  executor.run(taskflow).wait();
}

void tf::Task::reset()

resets the task handle to null

Resetting a task will remove its associated taskflow node and make it an empty task.

tf::Task task = taskflow.emplace([](){});
assert(task.empty() == false);
task.reset();
assert(task.empty() == true);

bool tf::Task::empty() const

queries if the task handle is associated with a taskflow node

tf::Task task;
assert(task.empty() == true);

Note that an empty task is not equal to a placeholder task. A placeholder task is created from tf::Taskflow::placeholder and is associated with a taskflow node, but its work is not assigned yet.

bool tf::Task::has_work() const

queries if the task has a work assigned

tf::Task task = taskflow.placeholder();
assert(task.has_work() == false);
// assign a static task callable to this task
task.work([](){});
assert(task.has_work() == true);

template<typename V>

void tf::Task::for_each_successor(V&& visitor) const

applies an visitor callable to each successor of the task

This method allows you to traverse and inspect successor tasks of this task. For instance, the code below iterates the two successors (task2 and task3) of task1.

auto [task1, task2, task3] = taskflow.emplace(
  [](){ std::cout << "task 1\n"; },
  [](){ std::cout << "task 2\n"; },
  [](){ std::cout << "task 3\n"; }
});
task1.precede(task2, task3);
task1.for_each_successor([](tf::Task successor){
  std::cout << "successor task " << successor.name() << '\n';
});

template<typename V>

void tf::Task::for_each_predecessor(V&& visitor) const

applies an visitor callable to each predecessor of the task

This method allows you to traverse and inspect predecessor tasks of this task. For instance, the code below iterates the two predecessors (task2 and task3) of task1.

auto [task1, task2, task3] = taskflow.emplace(
  [](){ std::cout << "task 1\n"; },
  [](){ std::cout << "task 2\n"; },
  [](){ std::cout << "task 3\n"; }
});
task1.succeed(task2, task3);
task1.for_each_predecessor([](tf::Task predecessor){
  std::cout << "predecessor task " << predecessor.name() << '\n';
});

template<typename V>

void tf::Task::for_each_subflow_task(V&& visitor) const

applies an visitor callable to each subflow task

This method allows you to traverse and inspect tasks within a subflow. It only applies to a subflow task.

tf::Task task = taskflow.emplace([](tf::Subflow& sf){
  tf::Task stask1 = sf.emplace([](){}).name("stask1");
  tf::Task stask2 = sf.emplace([](){}).name("stask2");
});
// Iterate tasks in the subflow and print each subflow task.
task.for_each_subflow_task([](tf::Task stask){
  std::cout << "subflow task " << stask.name() << '\n';
});

size_t tf::Task::hash_value() const

obtains a hash value of the underlying node

The method returns std::hash on the underlying node pointer.

tf::Task task = taskflow.emplace([](){});
std::cout << "hash value of task is " << task.hash_value() << '\n';

TaskType tf::Task::type() const

returns the task type

A task can be one of the types defined in tf::TaskType and can be printed in a human-readable form using tf::to_string.

auto task = taskflow.emplace([](){}).name("task");
std::cout << task.name() << " type=[" << tf::to_string(task.type()) << "]\n";

void tf::Task::dump(std::ostream& ostream) const

dumps the task through an output stream

The method dumps the name and the type of this task through the given output stream.

task.dump(std::cout);

void* tf::Task::data() const

queries pointer to user data

The following example shows how to attach a user data to a task and retrieve it during the execution of the task.

tf::Executor executor;
tf::Taskflow taskflow("attach data to a task");

int data;  // user data

// create a task and attach it a user data
auto A = taskflow.placeholder();
A.data(&data).work([A](){
  auto d = *static_cast<int*>(A.data());
  std::cout << "data is " << d << std::endl;
});

// run the taskflow iteratively with changing data
for(data = 0; data<10; data++){
  executor.run(taskflow).wait();
}

std::exception_ptr tf::Task::exception_ptr() const

retrieves the exception pointer of this task

This method retrieves the exception pointer of this task that are silently caught by the executor, if any. When multiple tasks throw exceptions concurrently, only one exception will be propagated, while the others are silently caught and stored within their respective tasks. For example, in the code below, both tasks B and C throw exceptions. However, only one of them will be propagated to the try-catch block, while the other will be silently caught and stored within its respective task.

tf::Executor executor(2); 
tf::Taskflow taskflow;
std::atomic<size_t> arrivals(0);

auto [B, C] = taskflow.emplace(
  [&]() { 
    // wait for two threads to arrive so we avoid premature cancellation
    ++arrivals; while(arrivals != 2);
    throw std::runtime_error("oops"); 
  },
  [&]() { 
    // wait for two threads to arrive so we avoid premature cancellation
    ++arrivals; while(arrivals != 2);
    throw std::runtime_error("oops"); 
  }
);

try {
  executor.run(taskflow).get();
}
catch (const std::runtime_error& e) {
  std::cerr << e.what();
}

// exactly one holds an exception as another was propagated to the try-catch block
assert((B.exception_ptr() != nullptr) != (C.exception_ptr() != nullptr));

bool tf::Task::has_exception_ptr() const

queries if the task has an exception pointer

The method checks whether the task holds a pointer to a silently caught exception.