carb::tasking::Future¶
Defined in carb/tasking/TaskingTypes.h
-
template<class
T
= void>
classcarb::tasking
::
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 resut. 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.
-
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
, classPeriod
>
boolwait_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
, classDuration
>
boolwait_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.
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 addTask() and related functions or from Promise::get_future(). Only Future objects returned from addTask() will return a valid pointer from task_if().
-
operator RequiredObject
() const¶ Convertible to RequiredObject.
-
template<class
Callable
, class ...Args
>
autothen
(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 cancelling 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 details::GenerateFuture