carb::tasking::Future

template<class T = void> class Future

A Future is a counterpart to a Promise.

It is the receiving end of a one-way, one-time asynchronous communication channel for transmitting the result of an asynchronous operation.

Future is very similar to std::future

Communication starts by creating a Promise. The Promise has an associated Future that can be retrieved once via Promise::get_future(). The Promise and the Future both reference a “shared state” that is used to communicate the result. When the result is available, it is set through Promise::set_value() (or the promise can be broken through Promise::setCanceled()), at which point the shared state becomes Ready and the Future will be able to retrieve the value through Future::get() (or determine cancellation via Future::isCanceled()).

Task functions like ITasking::addTask() return a Future where the Promise side is the return value from the callable passed when the task is created.

Future is inherently a “read-once” object. Once Future::get() is called, the Future becomes invalid. However, SharedFuture can be used (created via Future::share()) to retain the value. Many threads can wait on a SharedFuture and access the result simultaneously through SharedFuture::get().

There are three specializations of Future:

Future<T>: The base specialization, used to communicate objects between tasks/threads.
Future<T&>: Reference specialization, used to communicate references between tasks/threads.
Future<void>: Void specialization, used to communicate stateless events between tasks/threads.

The void specialization of Future is slightly different:

Future<void> does not have Future::isCanceled(); cancellation state cannot be determined.

Public Functions

constexpr Future() noexcept = default: Creates a future in an invalid state (valid() would return false).

~Future(): Destructor.

Future(Future &&rhs) noexcept: Futures are movable.

Future &operator=(Future &&rhs) noexcept: Futures are movable.

bool valid() const noexcept

Tests to see if this Future is valid.

Returns: true if get() and wait() are supported; false otherwise

bool try_wait() const

Checks to see if a value can be read from this Future.

Warning

Undefined behavior to call this if valid() == false.

Returns: true if a value can be read from this Future; false if the value is not yet ready

void wait() const: Waits until a value can be read from this Future.

Warning

Undefined behavior to call this if valid() == false.

template<class Rep, class Period> bool wait_for(const std::chrono::duration<Rep, Period> &dur) const

Waits until a value can be read from this Future, or the timeout period expires.

Warning

Undefined behavior to call this if valid() == false.

Parameters: dur – The relative timeout period.
Returns: true if a value can be read from this Future; false if the timeout period expires before the value can be read

template<class Clock, class Duration> bool wait_until(const std::chrono::time_point<Clock, Duration> &when) const

Waits until a value can be read from this Future, or the timeout period expires.

Warning

Undefined behavior to call this if valid() == false.

Parameters: when – The absolute timeout period.
Returns: true if a value can be read from this Future; false if the timeout period expires before the value can be read

T get()

Waits until the future value is ready and returns the value.

Resets the Future to an invalid state.

Warning

This function will call std::terminate() if the underlying task has been canceled with ITasking::tryCancelTask() or the Promise was broken. Use isCanceled() to determine if the value is safe to read.

Returns: The value passed to Promise::set_value().

bool isCanceled() const

Returns whether the Promise has been broken (or if this Future represents a task, the task has been canceled).

Note

The void specialization of Future does not have this function.

Warning

Undefined behavior to call this if valid() == false.

Returns: true if the task has been canceled; false if the task is still pending or has a valid value to read.

SharedFuture<T> share()

Transfers the Future’s shared state (if any) to a SharedFuture and leaves *this invalid (valid() == false).

Returns: A SharedFuture with the same shared state as *this.

const TaskContext *task_if() const

Returns a valid TaskContext if this Future represents a task.

Note

Futures can be returned from ITasking::addTask() and related functions or from Promise::get_future(). Only Future objects returned from ITasking::addTask() will return a valid pointer from task_if().

Returns: A pointer to a TaskContext if this Future was created from ITasking::addTask() or related functions; nullptr otherwise. The pointer is valid as long as the Future exists and the result from valid() is true.

operator RequiredObject() const: Convertible to RequiredObject.

template<class Callable, class ...Args> auto then(Priority prio, Trackers &&trackers, Callable &&f, Args&&... args)

Syntactic sugar around ITasking::addSubTask() that automatically passes the value from get() into Callable and resets the Future to an invalid state.

Note

This can be used to “chain” tasks together.

Warning

This resets the Future to an invalid state since the value is being consumed by the sub-task.

Warning

If the dependent task is canceled then the sub-task will call std::terminate(). When canceling the dependent task you must first cancel the sub-task.

Warning

For non-void specializations, it is undefined behavior to call this if valid() == false.

Parameters

prio – The priority of the task to execute.
trackers – (optional) A std::initializer_list of zero or more Tracker objects. Note that this must be a temporary object. The Tracker objects can be used to determine task completion or to provide input/output parameters to the task system.
f – A C++ “Callable” object (i.e. functor, lambda, [member] function ptr) that optionally returns a value. The Callable object must take the Future’s T type as its last parameter.
args – Arguments to pass to f

Returns

A Future based on the return type of f

Friends

friend struct detail::GenerateFuture