| Taskflow: A General-purpose Task-parallel Programming System

Loading...
Searching...
No Matches
Public Member Functions | Friends | List of all members
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
class to hold a dependent asynchronous task with shared ownership
Definition async_task.hpp:45

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());
tf::AsyncTask::empty
bool empty() const
checks if this dependent-async task is associated with any task
Definition async_task.hpp:268

## ◆ 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());
tf::AsyncTask::exception_ptr
std::exception_ptr exception_ptr() const
retrieves the exception pointer of this task
Definition async_task.hpp:258

## ◆ 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';
tf::AsyncTask::hash_value
size_t hash_value() const
obtains the hashed value of this dependent-async task
Definition async_task.hpp:279

## ◆ 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);
tf::AsyncTask::reset
void reset()
release the managed object of this
Definition async_task.hpp:273
tf::AsyncTask::is_done
bool is_done() const
checks if this dependent-async task finishes
Definition async_task.hpp:292

## ◆ 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);
tf::AsyncTask::use_count
size_t use_count() const
returns the number of shared owners that are currently managing this dependent-async task
Definition async_task.hpp:284

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

- taskflow/core/async_task.hpp