tf::AsyncTask class

class to hold a dependent asynchronous task with shared ownership

A tf::AsyncTask is a lightweight handle that retains shared ownership of a dependent asynchronous (dependent-async) task created by an executor. This shared ownership ensures that the dependent-async task remains alive when adding it to the dependency list of another dependent-async task, thus avoiding the classical ABA problem.

// main thread retains shared ownership of async task A
tf::AsyncTask A = executor.silent_dependent_async([](){});

// task A remains alive (i.e., at least one ref count by the main thread) 
// when being added to the dependency list of async task B
tf::AsyncTask B = executor.silent_dependent_async([](){}, A);

tf::AsyncTask is implemented based on the logic of C++ smart pointer std::shared_ptr and is considered cheap to copy or move as long as only a handful of objects own it. When a worker completes an async task, it will remove the task from the executor, decrementing the number of shared owners by one. If that counter reaches zero, the task is destroyed.

Constructors, destructors, conversion operators

AsyncTask() defaulted: constructs an empty task handle
~AsyncTask(): destroys the managed dependent-async task if this is the last owner
AsyncTask(const AsyncTask& rhs): constructs a dependent-async task that shares ownership of rhs
AsyncTask(AsyncTask&& rhs): move-constructs an dependent-async task from rhs

Public functions

auto operator=(const AsyncTask& rhs) -> AsyncTask&: copy-assigns the dependent-async task from rhs
auto operator=(AsyncTask&& rhs) -> AsyncTask&: move-assigns the dependent-async task from rhs
auto empty() const -> bool: checks if this dependent-async task is associated with any task
void reset(): release the managed object of this
auto hash_value() const -> size_t: obtains the hashed value of this dependent-async task
auto use_count() const -> size_t: returns the number of shared owners that are currently managing this dependent-async task
auto is_done() const -> bool: checks if this dependent-async task finishes
auto exception_ptr() const -> std::exception_ptr: retrieves the exception pointer of this task
auto has_exception_ptr() const -> bool: queries if the task has an exception pointer

Function documentation

AsyncTask& tf::AsyncTask::operator=(const AsyncTask& rhs)

copy-assigns the dependent-async task from rhs

Releases the managed object of this and retains a new shared ownership of rhs.

AsyncTask& tf::AsyncTask::operator=(AsyncTask&& rhs)

move-assigns the dependent-async task from rhs

Releases the managed object of this and takes over the ownership of rhs.

bool tf::AsyncTask::empty() const

checks if this dependent-async task is associated with any task

An empty dependent-async task is not associated with any task created from the executor.

tf::AsyncTask task;
assert(task.empty());

void tf::AsyncTask::reset()

release the managed object of this

Releases the ownership of the managed task, if any. After the call *this manages no task.

tf::AsyncTask task = executor.silent_dependent_async([](){});
assert(task.empty() == false);
task.reset();
assert(task.empty() == true);

size_t tf::AsyncTask::hash_value() const

obtains the hashed value of this dependent-async task

tf::AsyncTask task = executor.silent_dependent_async([](){});
std::cout << task.hash_value() << '\n';

size_t tf::AsyncTask::use_count() const

returns the number of shared owners that are currently managing this dependent-async task

In a multithreaded environment, use_count atomically retrieves (with memory_order_relaxed load) the number of tf::AsyncTask instances that manage the current task.

tf::AsyncTask task;
assert(task.use_count() == 0);

bool tf::AsyncTask::is_done() const

checks if this dependent-async task finishes

In a multithreaded environment, is_done atomically retrieves (with memory_order_acquire load) the underlying state bit that indicates the completion of this dependent-async task. If the dependent-async task is empty, returns true.

tf::AsyncTask task = executor.silent_dependent_async([](){});
while(task.is_done() == false);
std::cout << "dependent-async task finishes\n";

task.reset();
assert(task.is_done() == true);

std::exception_ptr tf::AsyncTask::exception_ptr() const

retrieves the exception pointer of this task

This method retrieves the exception pointer of the task, if any, that was silently caught by the executor. For example, the code below retrieves the exception pointer of a dependent-async task that does not have a shared state to propagate its exception.

tf::AsyncTask task = executor.silent_dependent_async([&](){
  throw std::runtime_error("oops"); 
});
executor.wait_for_all();

// propagate the exception to the outer caller
assert(task.exception_ptr() != nullptr);
std::rethrow_exception(task.exception_ptr());

bool tf::AsyncTask::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.