#include <future.h>

Inherits dispenso::detail::FutureBase< Result >.

Public Member Functions
	Future () noexcept

	Future (Future &&f) noexcept

	Future (Base &&f) noexcept

	Future (const Future &f) noexcept

	Future (const Base &f) noexcept

template<typename F , typename Schedulable >
	Future (F &&f, Schedulable &schedulable, std::launch asyncPolicy=kNotAsync, std::launch deferredPolicy=std::launch::deferred)

Future &	operator= (Future &&f) noexcept

Future &	operator= (const Future &f)

	~Future ()=default

bool	valid () const noexcept

bool	is_ready () const

void	wait () const

template<class Rep , class Period >
std::future_status	wait_for (const std::chrono::duration< Rep, Period > &timeoutDuration) const

template<class Clock , class Duration >
std::future_status	wait_until (const std::chrono::time_point< Clock, Duration > &timeoutTime) const

Future	share ()

const Result &	get () const

template<typename F , typename Schedulable >
Future< detail::ResultOf< F, Future< Result > && > >	then (F &&f, Schedulable &sched, std::launch asyncPolicy=kNotAsync, std::launch deferredPolicy=std::launch::deferred)

template<typename F >
Future< detail::ResultOf< F, Future< Result > && > >	then (F &&f)

Friends
template<typename T >
Future< std::decay_t< T > >	make_ready_future (T &&t)

Detailed Description

template<typename Result>
class dispenso::Future< Result >

A class that implements a hybrid of the interfaces for std::experimental::future, and std::experimental::shared_future. Future acts like a shared_future, but includes the share function in order to enable generic code that may use the function. See https://en.cppreference.com/w/cpp/experimental/future for more details on the API, but some differences are notable.

dispenso::Future are created and set into executors through their constructor, or through dispenso::async
dispenso::future can be shared around like std::experimental::shared_future, and wait/get functions may be called concurrently from multiple threads.

Future is thread-safe to call into, with the usual caveats (one thread may not be calling anything on the Future while another thread assigns to it or destructs it). It is thread-safe to assign or destruct on one copy of a Future while making calls on another copy of a Future with the same backing state.

Because Future is designed to work well with the dispenso TaskSet and ThreadPool, Future aggressively work steals in get and wait functions. This prevents deadlock due to thread pool resource starvation, similar to how TaskSets avoid that flavor of deadlock. It is important to note that deadlock is still possible due to traditional cyclic dependency, e.g. Future A and Future B which wait on each other. Just as with a cyclic mutex locking requirement, cyclic Future waits are considered programmer error.

Definition at line 69 of file future.h.

Constructor & Destructor Documentation

◆ Future() [1/6]

template<typename Result >

dispenso::Future< Result >::Future ( )

inlinenoexcept

Construct an invalid Future.

Definition at line 76 of file future.h.

◆ Future() [2/6]

template<typename Result >

dispenso::Future< Result >::Future ( Future< Result > && f )

inlinenoexcept

Move constructor

Parameters

f	The future to move from.

Definition at line 83 of file future.h.

◆ Future() [3/6]

template<typename Result >

dispenso::Future< Result >::Future ( Base && f )

inlinenoexcept

Definition at line 84 of file future.h.

◆ Future() [4/6]

template<typename Result >

dispenso::Future< Result >::Future ( const Future< Result > & f )

inlinenoexcept

Copy construct a Future.

Parameters

f	The existing future to reference. This essentially increments the reference count on the future's backing state.

Definition at line 92 of file future.h.

◆ Future() [5/6]

template<typename Result >

dispenso::Future< Result >::Future ( const Base & f )

inlinenoexcept

Definition at line 93 of file future.h.

◆ Future() [6/6]

template<typename Result >

template<typename F , typename Schedulable >

dispenso::Future< Result >::Future	(	F &&	f,
		Schedulable &	schedulable,
		std::launch	asyncPolicy = kNotAsync,
		std::launch	deferredPolicy = std::launch::deferred )

inline

Construct a Future with callable and a schedulable (e.g. a ThreadPool or TaskSet), and ensure it is scheduled according to the launch policy.

Parameters

f	a functor with signature `Result(void)` to be invoked in order for `get` to return a valid value.
schedulable	A `TaskSet`, `ThreadPool`, or similar type that has function `schedule` that takes a functor with signature `void()` and `ForceQueuingTag`.
asyncPolicy	If `std::launch::async`, the functor will be scheduled through to the underlying thread pool work queue.
deferredPolicy	If `std::launch::deferred`, `wait_for` and `wait_until` may invoke the functor from their calling thread.

Definition at line 110 of file future.h.

◆ ~Future()

template<typename Result >

dispenso::Future< Result >::~Future ( )

default

Destruct a Future. This decrements the shared reference count (if any), and ensures the backing state is destroyed when no more references exist to the backing state.

Member Function Documentation

◆ get()

template<typename Result >

const Result & dispenso::Future< Result >::get ( ) const

inline

Get the result of the future functor. This function blocks until the result is ready.

Returns: A const reference to the result's value.

Definition at line 218 of file future.h.

◆ is_ready()

template<typename Result >

bool dispenso::Future< Result >::is_ready ( ) const

inline

Is the Future ready?

Returns: true if the value associated with this Future has already be computed, and get can return the value immediately. Returns <false> if the functor is logically queued, or is in progress.

Definition at line 161 of file future.h.

◆ operator=() [1/2]

template<typename Result >

Future & dispenso::Future< Result >::operator= ( const Future< Result > & f )

inline

Copy a Future, which increments the underlying state reference count.

Parameters

f	The Future whose backing state will be referenced by this Future.

Definition at line 131 of file future.h.

◆ operator=() [2/2]

template<typename Result >

Future & dispenso::Future< Result >::operator= ( Future< Result > && f )

inlinenoexcept

Move a Future

Parameters

f	The Future whose backing state will be transferred to this Future.

Definition at line 122 of file future.h.

◆ share()

template<typename Result >

Future dispenso::Future< Result >::share ( )

inline

Provide a shared future. share is here only to provide compatible api with std::experimental::future, but Future already works like std::shared_future.

Definition at line 209 of file future.h.

◆ then() [1/2]

template<typename Result >

template<typename F >

Future< detail::ResultOf< F, Future< Result > && > > dispenso::Future< Result >::then ( F && f )

inline

Definition at line 250 of file future.h.

◆ then() [2/2]

template<typename Result >

template<typename F , typename Schedulable >

Future< detail::ResultOf< F, Future< Result > && > > dispenso::Future< Result >::then	(	F &&	f,
		Schedulable &	sched,
		std::launch	asyncPolicy = kNotAsync,
		std::launch	deferredPolicy = std::launch::deferred )

inline

Schedule a functor to be invoked upon reaching is_ready status, and return a future that will hold the result of the functor.

Parameters


  
    f The functor to be executed whose result will be available in the returned Future. This should have signature Unpecified(Future<Result>&&). 
    sched The Schedulable in which to run the functor. 
    asyncPolicy if std::launch::async then the functor will attempt to be queued on the backing work queue of the Schedulable (if any). 
    deferredPolicy if std::launch::deferred, wait_for and wait_until of the returned future will be allowed to invoke the functor, otherwise not.


Returns
A future containing the result of the functor.

Definition at line 239 of file future.h.

◆ valid()

template<typename Result >

bool dispenso::Future< Result >::valid ( ) const

inlinenoexcept

Is this Future valid?

Returns: true if the Future was constructed with a functor/schedulable, with result value, or indirectly from a Future that was constructed one of those ways. false if the Future was constructed via the default constructor, or indrectly from a Future that was constructed that way.

Definition at line 150 of file future.h.

◆ wait()

template<typename Result >

void dispenso::Future< Result >::wait ( ) const

inline

Wait until is_ready is true.

Note: This function will invoke the functor if it is still logically queued.

Definition at line 170 of file future.h.

◆ wait_for()

template<typename Result >

template<class Rep , class Period >

std::future_status dispenso::Future< Result >::wait_for ( const std::chrono::duration< Rep, Period > & timeoutDuration ) const

inline

Wait until is_ready is true or until timing out.

Parameters

timeoutDuration The length of time to wait until timing out. This is relative to the current point in time.

Returns: std::future_status::ready if get can return immediately, std::future_status::timeout if the function timed out while waiting.

Note: This function may invoke the functor if it is still logically queued, and std::launch::deferred was specified at construction.

Definition at line 186 of file future.h.

◆ wait_until()

template<typename Result >

template<class Clock , class Duration >

std::future_status dispenso::Future< Result >::wait_until ( const std::chrono::time_point< Clock, Duration > & timeoutTime ) const

inline

Wait until is_ready is true or until timing out.

Parameters

timeoutTime The absolute time to wait until timing out.

Returns: std::future_status::ready if get can return immediately, std::future_status::timeout if the function timed out while waiting.

Note: This function may invoke the functor if it is still logically queued, and std::launch::deferred was specified at construction.

Definition at line 201 of file future.h.

Friends And Related Symbol Documentation

◆ Future

template<typename Result >

template<typename R >

friend class Future

friend

Definition at line 264 of file future.h.

◆ make_ready_future

template<typename Result >

template<typename T >

Future< std::decay_t< T > > make_ready_future ( T && t )

friend

Make a Future in a ready state with the value passed into make_ready_future

Parameters

t	the value to use to create the returned future.

Definition at line 576 of file future.h.

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

/github/workspace/dispenso/future.h

f	The functor to be executed whose result will be available in the returned `Future`. This should have signature `Unpecified(Future<Result>&&)`.
sched	The Schedulable in which to run the functor.
asyncPolicy	if `std::launch::async` then the functor will attempt to be queued on the backing work queue of the Schedulable (if any).
deferredPolicy	if `std::launch::deferred`, `wait_for` and `wait_until` of the returned future will be allowed to invoke the functor, otherwise not.

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Future() [1/6]

◆ Future() [2/6]

◆ Future() [3/6]

◆ Future() [4/6]

◆ Future() [5/6]

◆ Future() [6/6]

◆ ~Future()

Member Function Documentation

◆ get()

◆ is_ready()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ share()

◆ then() [1/2]

◆ then() [2/2]

◆ valid()

◆ wait()

◆ wait_for()

◆ wait_until()

Friends And Related Symbol Documentation

◆ Future

◆ make_ready_future