tf::TaskGroup class

Executor& tf::TaskGroup::executor()

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);
});

template<typename F>

auto tf::TaskGroup::async(F&& f)

runs the given callable asynchronously

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 group
  for(int i=0; i<100; i++) {
    tg.silent_async([&](){ counter++; });
  }
  // corun until the 100 asynchronous tasks have completed
  tg.corun();
  assert(counter == 102);
  // do something else afterwards ...
});

template<typename P, typename F>

auto tf::TaskGroup::async(P&& params, F&& f)

runs the given callable asynchronously

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);
});

template<typename F>

void tf::TaskGroup::silent_async(F&& f)

runs the given function asynchronously without returning any future object

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);
});

template<typename P, typename F>

void tf::TaskGroup::silent_async(P&& params, F&& f)

runs the given function asynchronously without returning any future object

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();
});

template<typename F, typename... Tasks, std::enable_if_t<all_same_v<AsyncTask, std::decay_t<Tasks>...>, void>* = nullptr>

auto tf::TaskGroup::dependent_async(F&& func, Tasks && ... tasks)

runs the given function asynchronously when the given predecessors finish

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()
});

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 tf::TaskGroup::dependent_async(P&& params, F&& func, Tasks && ... tasks)

runs the given function asynchronously when the given predecessors finish

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()
});

template<typename F, typename I, std::enable_if_t<!std::is_same_v<std::decay_t<I>, AsyncTask>, void>* = nullptr>

auto tf::TaskGroup::dependent_async(F&& func, I first, I last)

runs the given function asynchronously when the given range of predecessors finish

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()
}); 

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 tf::TaskGroup::dependent_async(P&& params, F&& func, I first, I last)

runs the given function asynchronously when the given range of predecessors finish

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()
});

template<typename F, typename... Tasks, std::enable_if_t<all_same_v<AsyncTask, std::decay_t<Tasks>...>, void>* = nullptr>

tf::AsyncTask tf::TaskGroup::silent_dependent_async(F&& func, Tasks && ... tasks)

runs the given function asynchronously when the given predecessors finish

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
});

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>

tf::AsyncTask tf::TaskGroup::silent_dependent_async(P&& params, F&& func, Tasks && ... tasks)

runs the given function asynchronously when the given predecessors finish

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
}); 

template<typename F, typename I, std::enable_if_t<!std::is_same_v<std::decay_t<I>, AsyncTask>, void>* = nullptr>

tf::AsyncTask tf::TaskGroup::silent_dependent_async(F&& func, I first, I last)

runs the given function asynchronously when the given range of predecessors finish

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
}); 

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>

tf::AsyncTask tf::TaskGroup::silent_dependent_async(P&& params, F&& func, I first, I last)

runs the given function asynchronously when the given range of predecessors finish

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
}); 

void tf::TaskGroup::corun()

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 wait
  for(int i=0; i<100; i++) {
    tg.silent_async([&](){ counter++; });
  }
  tg.corun();
  assert(counter == 100);
  
  // spawn another 100 async tasks and wait
  for(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.

void tf::TaskGroup::cancel()

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 work
tf::Executor executor(W);

executor.async([&executor, W](){

  auto tg = executor.task_group();

  // deliberately block the other W-1 workers
  std::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 blocked
  while(latch != W-1);

  // spawn other tasks which should never run after cancellation
  for(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 workers
  assert(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.

bool tf::TaskGroup::is_cancelled()

queries if the task group has been cancelled

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.

size_t tf::TaskGroup::size() const

queries 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();
});