carb::tasking::SharedFuture¶
Defined in carb/tasking/TaskingTypes.h
-
template<class
T
= void>
classcarb::tasking
::
SharedFuture
¶ SharedFuture is a sharable version of Future.
Instead of Future::get() invalidating the Future and returning the value one time, multiple SharedFuture objects can reference the same shared state and allow multiple threads to wait and access the result value simultaneously.
SharedFuture is similar to std::shared_future
The same specializations (and their limitations) exist as with Future.
Public Functions
-
SharedFuture
() noexcept = default¶ Default constructor.
Constructs a SharedFuture where valid() ==
false
.
-
SharedFuture
(const SharedFuture<T> &other) noexcept¶ Copy constructor.
Holds the same state (if any) as
other
.- Parameters
other – A SharedFuture to copy state from.
-
SharedFuture
(SharedFuture<T> &&other) noexcept¶ Move constructor.
Moves the shared state (if any) from
other
.After this call,
other
will report valid() ==false
.- Parameters
other – A SharedFuture to move state from.
-
SharedFuture
(Future<T> &&fut) noexcept¶ Transfers the shared state (if any) from
fut
.After construction,
fut
will report valid() ==false
.- Parameters
fut – A Future to move state from.
-
~SharedFuture
()¶ Destructor.
-
SharedFuture<T> &
operator=
(const SharedFuture<T> &other)¶ Copy-assign operator.
Holds the same state (if any) as
other
after releasing any shared state previously held.- Parameters
other – A SharedFuture to copy state from.
- Returns
*this
-
SharedFuture<T> &
operator=
(SharedFuture<T> &&other) noexcept¶ Move-assign operator.
Swaps shared states with
other
.- Parameters
other – A SharedFuture to swap states with.
- Returns
*this
-
const T &
get
() const¶ Waits until the shared state is Ready and retrieves the value stored.
Warning
Undefined behavior if valid() ==
false
.- Returns
A const reference to the stored value.
-
bool
valid
() const noexcept¶ Checks if the SharedFuture references a shared state.
This is only
true
for default-constructed SharedFuture or when moved from. Unlike Future, SharedFuture does not invalidate once the value is read with Future::get().- Returns
true
if this SharedFuture references a shared state;false
otherwise.
-
bool
try_wait
() const¶ Checks to see if the shared state is Ready without waiting.
Warning
Undefined behavior to call this if valid() ==
false
.- Returns
true
if the shared state is Ready;false
otherwise.
-
void
wait
() const¶ Blocks the task or thread and waits for the shared state to become Ready.
try_wait() ==
true
after this call and get() will immediately return a value.Warning
Undefined behavior to call this if valid() ==
false
.
-
template<class
Rep
, classPeriod
>
boolwait_for
(const std::chrono::duration<Rep, Period> &dur) const¶ Blocks the task or thread until
dur
has elapsed or the shared state becomes Ready.If
true
is returned, get() will return a value immediately.Warning
Undefined behavior to call this if valid() ==
false
.- Parameters
dur – The duration to wait for.
- Returns
true
If the shared state is Ready;false
if the timeout period elapsed.
-
template<class
Clock
, classDuration
>
boolwait_until
(const std::chrono::time_point<Clock, Duration> &when) const¶ Blocks the task or thread until
when
is reached or the shared state becomes Ready.If
true
is returned, get() will return a value immediately.Warning
Undefined behavior to call this if valid() ==
false
.- Parameters
when – The clock time to wait until.
- Returns
true
If the shared state is Ready;false
if the timeout period elapsed.
-
bool
isCanceled
() const¶ Returns whether the task promising a value to this Future has been canceled.
Note
The
void
specialization of SharedFuture does not have this function.Warning
Undefined behavior to call this if valid() ==
false
.- Returns
true
if the task has been canceled or promise broken;false
if the task is still pending, promise not yet fulfilled, or has a valid value to read.
-
operator RequiredObject
() const¶ Convertible to RequiredObject.
-
const TaskContext *
task_if
() const¶ Returns a valid TaskContext if this SharedFuture represents a task.
Note
Futures can be returned from addTask() and related functions or from Promise::get_future(). Only Future objects returned from addTask() and transfered to SharedFuture will return a valid pointer from task_if().
- Returns
A pointer to a TaskContext if this SharedFuture was created from addTask() or related functions;
nullptr
otherwise. The pointer is valid as long as the SharedFuture exists and the response from valid() would be consistent.
-
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
.Unlike Future::then(), the SharedFuture is not reset to an invalid state.
Note
This can be used to “chain” tasks together.
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.- 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
const T&
as its last parameter.args – Arguments to pass to
f
- Returns
A Future based on the return type of
f
-