tf::AsyncTask Class Reference

class to hold a dependent asynchronous task with shared ownership More...

#include <taskflow/core/async_task.hpp>

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

Friends
class	Executor

Detailed Description

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.

Note

To know more about dependent-async task, please refer to Asynchronous Tasking with Dependencies.

Member Function Documentation

empty()

bool tf::AsyncTask::empty ( ) const

inline

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

exception_ptr()

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

inline

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

has_exception_ptr()

bool tf::AsyncTask::has_exception_ptr ( ) const

inline

queries if the task has an exception pointer

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

hash_value()

size_t tf::AsyncTask::hash_value ( ) const

inline

obtains the hashed value of this dependent-async task

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

is_done()

bool tf::AsyncTask::is_done ( ) const

inline

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

operator=() [1/2]

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

inline

move-assigns the dependent-async task from rhs

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

operator=() [2/2]

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

inline

copy-assigns the dependent-async task from rhs

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

reset()

void tf::AsyncTask::reset ( )

inline

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

use_count()

size_t tf::AsyncTask::use_count ( ) const

inline

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

---

The documentation for this class was generated from the following file:

• taskflow/core/async_task.hpp