carb::tasking::SharedFuture

template<class T = void> class SharedFuture

SharedFuture is a shareable 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, class Period> bool wait_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, class Duration> bool wait_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 transferred 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> auto then(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 canceling 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