BloombergLP::rmqt::Future< T > Class Template Reference

An async-style Future/Promise object. More...

Classes
class	Impl

Public Types
typedef bsl::function< void(const Result< T > &result)>	Maker
	Used to resolve a Future<T>. Somewhat equivalent to std::promise.
typedef bsl::pair< typename Future< T >::Maker, Future< T > >	Pair
	A (Promise, Future) pair. Used to create Futures.

Public Member Functions
	~Future ()
	Destructor.
Result< T >	tryResult ()
	Attempt to fetch the result, do not block. More...
Result< T >	blockResult ()
	Fetch the result, and block if it isn't ready yet. More...
Result< T >	timedWaitResult (const bsls::TimeInterval &absoluteTime)
	Fetch the result, waiting up to absoluteTime if it isn't ready. More...
Result< T >	waitResult (const bsls::TimeInterval &relativeTimeout)
	Fetch the result, waiting up to relativeTimeout period (from now) if it isn't ready. More...
	Future (const Result< T > &result)
	instantly resolved future
	Future (const Future &future)
	Copy construct this Future. More...
Future &	operator= (const Future &future)
	Assignment (copy) Future. More...
template<typename newT >
Future< newT >	then (const bsl::function< Result< newT >(const Result< T > &)> &converter)
template<typename newT >
Future< newT >	thenFuture (const bsl::function< Future< newT >(const Result< T > &)> &nextFuture)

Static Public Member Functions
static Pair	make ()
	Creates a pair of (Promise, Future). More...
static Pair	make (const bsl::function< void()> &cancelFunction)
	Create a pair of (Promise, Future) with a cancel function. More...

Detailed Description

template<typename T = void>
class BloombergLP::rmqt::Future< T >

An async-style Future/Promise object.

Future<T> Represents an action which may or may not have completed yet. Future<T>::Maker completes an associated Future object.

Each Future holds shared ownership of a Control Block (Impl). Copying an existing Future always shares the existing control block. Creating a new future through Future<T>::make always creates a new standalone control block.

Future objects are cancellable. Any cancel function passed to Future<T>::make is called and then destroyed when a Control Block is destructed.

One or more bsl::function objects may be scheduled to run upon the completion of a Future object via Future<T>::then and Future<T>::thenFuture. If scheduled, these are executed from within the Future<T>::Maker call.

Future<T>::then/thenFuture both return a Future object with a new Control Block. The new Control Block shares ownership of the original Future's control block.

Demonstration: Pair a = Future<T>::make(); Future<T> b = a.then([](const rmqt::Result<T>& res){ return res; });

      a: Fut A     b: Fut B
          |            |
          V            V
         CB A <------ CB B

thenFuture Demonstration: Future<T>::Pair a = Future<T>::make(); Future<T> b = a.thenFuture([](const rmqt::Result<T>& res) { Future<T> c = Future<c>::make(); return c; });

Ownership model prior to a being resolved: a.2nd: Fut A b: Fut B | | V V CB A <---— CB B

Ownership after a is resolved:

   a.2nd: Fut A    b: Fut B     c: Fut C     d: Fut D
           |            |           |             |
           V            V           V             V
          CB A         CB B        CB C <------- CB D
                        |                         ^
                        |                         |
                        --------------------------- 

Constructor & Destructor Documentation

Future()

template<typename T >

BloombergLP::rmqt::Future< T >::Future

(

const Future< T > &

future

)

Copy construct this Future.

Both Futures remain valid, and can be used safely from different threads.

Member Function Documentation

blockResult()

template<typename T >

Result< T > BloombergLP::rmqt::Future< T >::blockResult

Fetch the result, and block if it isn't ready yet.

This method will always return the result passed by the Promise.

make() [1/2]

template<typename T >

bsl::pair< typename Future< T >::Maker, Future< T > > BloombergLP::rmqt::Future< T >::make

static

Creates a pair of (Promise, Future).

The Future is used by the 'receiver' to wait on the completed work. The Promise is used to complete the Future.

make() [2/2]

template<typename T >

bsl::pair< typename Future< T >::Maker, Future< T > > BloombergLP::rmqt::Future< T >::make ( const bsl::function< void()> &  cancelFunction )

static

Create a pair of (Promise, Future) with a cancel function.

See Future<T>::make() for info on Promise & Future

Parameters

cancelFunction

is called when no Future exists to listen for the result: This Future and all chained Futures have been destructed.

operator=()

template<typename T >

Future< T > & BloombergLP::rmqt::Future< T >::operator=

(

const Future< T > &

future

)

Assignment (copy) Future.

Both remaining Futures remain valid, and can be used safely from different threads.

timedWaitResult()

template<typename T >

Result< T > BloombergLP::rmqt::Future< T >::timedWaitResult

(

const bsls::TimeInterval &

absoluteTime

)

Fetch the result, waiting up to absoluteTime if it isn't ready.

Parameters

absoluteTime

is an absolute point in time e.g. , not a relative to now time period.

Returns

The resolved result, or a timeout Result

tryResult()

template<typename T >

Result< T > BloombergLP::rmqt::Future< T >::tryResult

Attempt to fetch the result, do not block.

tryResult will return the Result<T> if the Promise for this future has been executed. If the Future has not been resolved, the Result<T> is falsey, and will have the returnCode rmqt::ReturnCodes::TIMEOUT

waitResult()

template<typename T >

Result< T > BloombergLP::rmqt::Future< T >::waitResult

(

const bsls::TimeInterval &

relativeTimeout

)

Fetch the result, waiting up to relativeTimeout period (from now) if it isn't ready.

Parameters

relativeTimeout

is a relative time (e.g. 5 seconds), not an absolute point in time.

Returns

The resolved result, or a timeout Result.

---

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

• src/rmq/rmqt/rmqt_future.h