docs/classtf_1_1TaskGroup.html
class to create a task group from a task
A task group executes a group of asynchronous tasks. It enables asynchronous task spawning, cooperative execution among worker threads, and naturally supports recursive parallelism. Due to cooperative execution, a task group can only be created by an executor worker; otherwise an exception will be thrown. The code below demonstrates how to use task groups to implement recursive Fibonacci parallelism.
tf::Executor executor;size\_t fibonacci(size\_t N) {if (N \< 2) return N;size\_t res1, res2;// Create a task group from the current executortf::TaskGroup tg = get\_executor().task\_group();// Submit asynchronous tasks to the grouptg.silent\_async(N, &res1{ res1 = fibonacci(N-1); });res2 = fibonacci(N-2);// compute one branch synchronously// Wait for all tasks in the group to completetg.corun();return res1 + res2;}int main() {size\_t N = 30, res;res = executor.async([](){ return fibonacci(30); }).get();std::cout \<\< N \<\< "-th Fibonacci number is " \<\< res \<\< '\n';return 0;}
Users must explicitly call tf::TaskGroup::corun() to ensure that all tasks have completed or been properly canceled before leaving the scope of a task group. Failing to do so results in undefined behavior.
TaskGroup(const TaskGroup&) deleteddisabled copy constructorTaskGroup(TaskGroup&&) deleteddisabled move constructor
auto operator=(TaskGroup&&) -> TaskGroup& deleteddisabled copy assignmentauto operator=(const TaskGroup&) -> TaskGroup& deleteddisabled move assignmentauto executor() -> Executor&obtains the executor that creates this task group template<typename F> auto async(F&& f) -> autoruns the given callable asynchronously template<typename P, typename F> auto async(P&& params, F&& f) -> autoruns the given callable asynchronously template<typename F> void silent_async(F&& f)runs the given function asynchronously without returning any future object template<typename P, typename F> void silent_async(P&& params, F&& f)runs the given function asynchronously without returning any future object template<typename F, typename... Tasks, std::enable_if_t<all_same_v<AsyncTask, std::decay_t<Tasks>...>, void>* = nullptr> auto dependent_async(F&& func, Tasks && ... tasks) -> autoruns the given function asynchronously when the given predecessors finish template<typename P, typename F, typename... Tasks, std::enable_if_t<is_task_params_v<P> && all_same_v<AsyncTask, std::decay_t<Tasks>...>, void>* = nullptr> auto dependent_async(P&& params, F&& func, Tasks && ... tasks) -> autoruns the given function asynchronously when the given predecessors finish template<typename F, typename I, std::enable_if_t<!std::is_same_v<std::decay_t<I>, AsyncTask>, void>* = nullptr> auto dependent_async(F&& func, I first, I last) -> autoruns the given function asynchronously when the given range of predecessors finish template<typename P, typename F, typename I, std::enable_if_t<is_task_params_v<P> && !std::is_same_v<std::decay_t<I>, AsyncTask>, void>* = nullptr> auto dependent_async(P&& params, F&& func, I first, I last) -> autoruns the given function asynchronously when the given range of predecessors finish template<typename F, typename... Tasks, std::enable_if_t<all_same_v<AsyncTask, std::decay_t<Tasks>...>, void>* = nullptr> auto silent_dependent_async(F&& func, Tasks && ... tasks) -> tf::AsyncTaskruns the given function asynchronously when the given predecessors finish template<typename P, typename F, typename... Tasks, std::enable_if_t<is_task_params_v<P> && all_same_v<AsyncTask, std::decay_t<Tasks>...>, void>* = nullptr> auto silent_dependent_async(P&& params, F&& func, Tasks && ... tasks) -> tf::AsyncTaskruns the given function asynchronously when the given predecessors finish template<typename F, typename I, std::enable_if_t<!std::is_same_v<std::decay_t<I>, AsyncTask>, void>* = nullptr> auto silent_dependent_async(F&& func, I first, I last) -> tf::AsyncTaskruns the given function asynchronously when the given range of predecessors finish template<typename P, typename F, typename I, std::enable_if_t<is_task_params_v<P> && !std::is_same_v<std::decay_t<I>, AsyncTask>, void>* = nullptr> auto silent_dependent_async(P&& params, F&& func, I first, I last) -> tf::AsyncTaskruns the given function asynchronously when the given range of predecessors finishvoid corun()corun all tasks spawned by this task group with other workersvoid cancel()cancel all tasks in this task groupauto is_cancelled() -> boolqueries if the task group has been cancelledauto size() const -> size_tqueries the number of tasks currently in this task group
obtains the executor that creates this task group
The running executor of a task group is the executor that creates the task group.
executor.silent\_async(&{tf::TaskGroup tg = executor.task\_group();assert(&(tg.executor()) == &executor);});
runs the given callable asynchronously
| Template parameters |
|---|
| F |
| Parameters |
| --- |
| f |
This method creates an asynchronous task that executes the given function with the specified arguments. Unlike tf::Executor::async, the task created here is parented to the task group, where applications can issue tf::TaskGroup::corun to explicitly wait for all asynchronous tasks spawned from the task group to complete. For example:
executor.silent\_async(&{std::atomic\<int\> counter(0);auto tg = executor.task\_group();auto fu1 = tg.async(&{ counter++; });auto fu2 = tg.async(&{ counter++; });fu1.get();fu2.get();assert(counter == 2);// spawn 100 asynchronous tasks from the task groupfor(int i=0; i\<100; i++) {tg.silent\_async(&{ counter++; });}// corun until the 100 asynchronous tasks have completedtg.corun();assert(counter == 102);// do something else afterwards ...});
runs the given callable asynchronously
| Template parameters |
|---|
| P |
| F |
| Parameters |
| --- |
| params |
| f |
Similar to tf::TaskGroup::async, but takes a parameter of type tf::TaskParams to initialize the asynchronous task.
executor.silent\_async(&{auto tg = executor.task\_group();auto future = tg.async("my task", [](){ return 10; });assert(future.get() == 10);});
runs the given function asynchronously without returning any future object
| Template parameters |
|---|
| F |
| Parameters |
| --- |
| f |
This function is more efficient than tf::TaskGroup::async and is recommended when the result of the asynchronous task does not need to be accessed via a std::future.
executor.silent\_async(&{std::atomic\<int\> counter(0);auto tg = executor.task\_group();for(int i=0; i\<100; i++) {tg.silent\_async(&{ counter++; });}tg.corun();assert(counter == 100);});
runs the given function asynchronously without returning any future object
| Template parameters |
|---|
| F |
| Parameters |
| --- |
| params |
| f |
Similar to tf::TaskGroup::silent_async, but takes a parameter of type tf::TaskParams to initialize the created asynchronous task.
executor.silent\_async(&{auto tg = executor.task\_group();tg.silent\_async("my task", [](){});tg.corun();});
runs the given function asynchronously when the given predecessors finish
| Template parameters |
|---|
| F |
| Tasks |
| Parameters |
| --- |
| func |
| tasks |
| Returns |
The example below creates three asynchronous tasks, A, B, and C, in which task C runs after task A and task B. Task C returns a pair of its tf::AsyncTask handle and a std::future<int> that eventually will hold the result of the execution.
executor.silent\_async(&{auto tg = executor.task\_group();tf::AsyncTask A = tg.silent\_dependent\_async([](){ printf("A\n"); });tf::AsyncTask B = tg.silent\_dependent\_async([](){ printf("B\n"); });auto [C, fuC] = tg.dependent\_async([](){ printf("C runs after A and B\n"); return 1;}, A, B);fuC.get();// C finishes, which in turns means both A and B finish,// so we don't need tg.corun()});
runs the given function asynchronously when the given predecessors finish
| Template parameters |
|---|
| P |
| F |
| Tasks |
| Parameters |
| --- |
| params |
| func |
| tasks |
| Returns |
The example below creates three named asynchronous tasks, A, B, and C, in which task C runs after task A and task B. Task C returns a pair of its tf::AsyncTask handle and a std::future<int> that eventually will hold the result of the execution. Assigned task names will appear in the observers of the executor.
executor.silent\_async(&{auto tg = executor.task\_group();tf::AsyncTask A = tg.silent\_dependent\_async("A", [](){ printf("A\n"); });tf::AsyncTask B = tg.silent\_dependent\_async("B", [](){ printf("B\n"); });auto [C, fuC] = tg.dependent\_async("C",[](){ printf("C runs after A and B\n"); return 1;}, A, B);fuC.get();// C finishes, which in turns means both A and B finish,// so we don't need tg.corun()});
runs the given function asynchronously when the given range of predecessors finish
| Template parameters |
|---|
| F |
| I |
| Parameters |
| --- |
| func |
| first |
| last |
| Returns |
The example below creates three asynchronous tasks, A, B, and C, in which task C runs after task A and task B. Task C returns a pair of its tf::AsyncTask handle and a std::future<int> that eventually will hold the result of the execution.
executor.silent\_async([](){auto tg = executor.task\_group();std::array\<tf::AsyncTask, 2\> array {tg.silent\_dependent\_async([](){ printf("A\n"); }),tg.silent\_dependent\_async([](){ printf("B\n"); })};auto [C, fuC] = tg.dependent\_async([](){ printf("C runs after A and B\n"); return 1;}, array.begin(), array.end());fuC.get();// C finishes, which in turns means both A and B finish,// so we don't need tg.corun()});
runs the given function asynchronously when the given range of predecessors finish
| Template parameters |
|---|
| P |
| F |
| I |
| Parameters |
| --- |
| params |
| func |
| first |
| last |
| Returns |
The example below creates three named asynchronous tasks, A, B, and C, in which task C runs after task A and task B. Task C returns a pair of its tf::AsyncTask handle and a std::future<int> that eventually will hold the result of the execution. Assigned task names will appear in the observers of the executor.
executor.silent\_async(&{auto tg = executor.task\_group();std::array\<tf::AsyncTask, 2\> array {tg.silent\_dependent\_async("A", [](){ printf("A\n"); }),tg.silent\_dependent\_async("B", [](){ printf("B\n"); })};auto [C, fuC] = tg.dependent\_async("C",[](){ printf("C runs after A and B\n"); return 1;}, array.begin(), array.end());fuC.get();// C finishes, which in turns means both A and B finish,// so we don't need tg.corun()});
runs the given function asynchronously when the given predecessors finish
| Template parameters |
|---|
| F |
| Tasks |
| Parameters |
| --- |
| func |
| tasks |
| Returns |
This member function is more efficient than tf::TaskGroup::dependent_async and is encouraged to use when you do not want a std::future to acquire the result or synchronize the execution. The example below creates three asynchronous tasks, A, B, and C, in which task C runs after task A and task B.
executor.silent\_async(&{auto tg = executor.task\_group();tf::AsyncTask A = tg.silent\_dependent\_async([](){ printf("A\n"); });tf::AsyncTask B = tg.silent\_dependent\_async([](){ printf("B\n"); });tg.silent\_dependent\_async([](){ printf("C runs after A and B\n"); }, A, B);tg.corun();// corun until all dependent-async tasks finish});
runs the given function asynchronously when the given predecessors finish
| Template parameters |
|---|
| F |
| Tasks |
| Parameters |
| --- |
| params |
| func |
| tasks |
| Returns |
This member function is more efficient than tf::TaskGroup::dependent_async and is encouraged to use when you do not want a std::future to acquire the result or synchronize the execution. The example below creates three asynchronous tasks, A, B, and C, in which task C runs after task A and task B. Assigned task names will appear in the observers of the executor.
executor.silent\_async(&{auto tg = executor.task\_group();tf::AsyncTask A = tg.silent\_dependent\_async("A", [](){ printf("A\n"); });tf::AsyncTask B = tg.silent\_dependent\_async("B", [](){ printf("B\n"); });tg.silent\_dependent\_async("C", [](){ printf("C runs after A and B\n"); }, A, B);tg.corun();// corun until all dependent-async tasks finish});
runs the given function asynchronously when the given range of predecessors finish
| Template parameters |
|---|
| F |
| I |
| Parameters |
| --- |
| func |
| first |
| last |
| Returns |
This member function is more efficient than tf::TaskGroup::dependent_async and is encouraged to use when you do not want a std::future to acquire the result or synchronize the execution. The example below creates three asynchronous tasks, A, B, and C, in which task C runs after task A and task B.
executor.silent\_async(&{auto tg = executor.task\_group();std::array\<tf::AsyncTask, 2\> array {tg.silent\_dependent\_async([](){ printf("A\n"); }),tg.silent\_dependent\_async([](){ printf("B\n"); })};tg.silent\_dependent\_async([](){ printf("C runs after A and B\n"); }, array.begin(), array.end());tg.corun();// corun until all dependent-async tasks finish});
runs the given function asynchronously when the given range of predecessors finish
| Template parameters |
|---|
| F |
| I |
| Parameters |
| --- |
| params |
| func |
| first |
| last |
| Returns |
This member function is more efficient than tf::TaskGroup::dependent_async and is encouraged to use when you do not want a std::future to acquire the result or synchronize the execution. The example below creates three asynchronous tasks, A, B, and C, in which task C runs after task A and task B. Assigned task names will appear in the observers of the executor.
executor.silent\_async(&{auto tg = executor.task\_group();std::array\<tf::AsyncTask, 2\> array {tg.silent\_dependent\_async("A", [](){ printf("A\n"); }),tg.silent\_dependent\_async("B", [](){ printf("B\n"); })};tg.silent\_dependent\_async("C", [](){ printf("C runs after A and B\n"); }, array.begin(), array.end());tg.corun();// corun until all dependent-async tasks finish});
corun all tasks spawned by this task group with other workers
Coruns all tasks spawned by this task group cooperatively with other workers in the same executor until all these tasks finish. Under cooperative execution, a worker is not preempted. Instead, it continues participating in the work-stealing loop, executing available tasks alongside other workers.
executor.silent\_async(&{auto tg = executor.task\_group();std::atomic\<size\_t\> counter{0};// spawn 100 async tasks and waitfor(int i=0; i\<100; i++) {tg.silent\_async(&{ counter++; });}tg.corun();assert(counter == 100);// spawn another 100 async tasks and waitfor(int i=0; i\<100; i++) {tg.silent\_async(&{ counter++; });}tg.corun();assert(counter == 200);});
Note that only the parent worker of this task group (the worker who creates it) can call this corun.
cancel all tasks in this task group
Marks the task group as cancelled to stop any not-yet-started tasks in the group from running. Tasks that are already running will continue to completion, but no new tasks belonging to the task group will be scheduled after cancellation.
This example below demonstrates how tf::TaskGroup::cancel() prevents pending tasks in a task group from executing, while allowing already running tasks to complete cooperatively. The first set of tasks deliberately occupies all but one worker thread, ensuring that subsequently spawned tasks remain pending. After invoking tf::TaskGroup::cancel(), these pending tasks are never scheduled, even after the blocked workers are released. A final call to tf::TaskGroup::corun() synchronizes with all tasks in the group, guaranteeing safe completion and verifying that cancellation successfully suppresses task execution.
const size\_t W = 12;// must be \>1 for this example to worktf::Executor executor(W);executor.async(&executor, W{auto tg = executor.task\_group();// deliberately block the other W-1 workersstd::atomic\<size\_t\> latch(0);for(size\_t i=0; i\<W-1; ++i) {tg.async(&{++latch;while(latch != 0);});}// wait until the other W-1 workers are blockedwhile(latch != W-1);// spawn other tasks which should never run after cancellationfor(size\_t i=0; i\<100; ++i) {tg.async(&{ throw std::runtime\_error("this should never run"); });}// cancel the task group and unblock the other W-1 workersassert(tg.is\_cancelled() == false);tg.cancel();assert(tg.is\_cancelled() == true);latch = 0;tg.corun();});
Note that cancellation is cooperative: tasks should not assume immediate termination. Users must still call tf::TaskGroup::corun() to synchronize with all spawned tasks and ensure safe completion or cancellation. Failing to do so results in undefined behavior.
queries if the task group has been cancelled
| Returns | true if the task group has been marked as cancelled or false otherwise |
This method returns true if the task group has been marked as cancelled via a call to cancel(), and false otherwise.
executor.async(&{auto tg = executor.task\_group();assert(tg.is\_cancelled() == false);tg.cancel(true);assert(tg.is\_cancelled() == false);});
The cancellation state reflects whether the task group is currently in a cancelled state and does not imply that all tasks have completed or been synchronized. If a task group spawns any task, users must still call corun() to synchronize with all spawned tasks and ensure safe completion or cancellation. Failing to do so results in undefined behavior.
queries the number of tasks currently in this task group
| Returns | the number of tasks currently in this task group |
This method returns the number of tasks that belong to the task group at the time of the call. The returned value represents a snapshot and may become outdated immediately, as tasks can be concurrently spawned, started, completed, or canceled while this method is executing. As a result, the value returned by size() should be used for informational or diagnostic purposes only and must not be relied upon for synchronization or correctness.
executor.silent\_async(&{auto tg = executor.task\_group();assert(tg.size() == 0);for(size\_t i=0; i\<1000; ++i) {tg.silent\_async([](){});}assert(tg.size() \>= 0);tg.corun();});