libqi-api  2.8.7.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
qi::Future< T > Class Template Reference

#include <executioncontext.hpp>

Public Types

using ValueType = typename detail::FutureType< T >::type
 
using ValueTypeCast = typename detail::FutureType< T >::typecast
 
using TemplateValue = T
 
using Connection = boost::function< void(Future< T >)>
 

Public Member Functions

 Future ()
 
 Future (const Future< T > &b)
 
bool operator== (const Future< T > &other) const
 
Future< T > & operator= (const Future< T > &b)
 
bool operator< (const Future< T > &b) const
 
FutureUniqueId uniqueId () const
 
bool isValid () const
 
 Future (const ValueType &v, FutureCallbackType async=FutureCallbackType_Auto)
 
const ValueTypevalue (int msecs=FutureTimeout_Infinite) const
 Return the value associated to a Future. More...
 
const ValueTypevalue (Either< MilliSeconds, Infinity > timeout) const
 
ValueType valueCopy (Either< MilliSeconds, Infinity > timeout=Infinity{}) const
 Return by copy the value associated to a Future. More...
 
boost::shared_ptr< const T > valueSharedPtr (Either< MilliSeconds, Infinity > timeout=Infinity{}) const
 Return a shared pointer to the value associated to a Future. More...
 
ValueType operator* () const
 Return the value associated to a Future. More...
 
 operator const ValueTypeCast & () const
 
FutureState wait (int msecs=FutureTimeout_Infinite) const
 
FutureState wait (qi::Duration duration) const
 
FutureState waitFor (qi::Duration duration) const
 
FutureState wait (qi::SteadyClock::time_point timepoint) const
 
FutureState waitUntil (qi::SteadyClock::time_point timepoint) const
 
bool isFinished () const
 
bool isRunning () const
 
bool isCanceled () const
 
bool hasError (int msecs=FutureTimeout_Infinite) const
 
bool hasValue (int msecs=FutureTimeout_Infinite) const
 
const std::string & error (int msecs=FutureTimeout_Infinite) const
 
FutureSync< T > sync ()
 
void cancel ()
 
bool isCancelable () const
 
template<typename R , typename AF >
Future< R > thenR (FutureCallbackType type, AF &&func)
 Execute a callback when the future is finished. More...
 
template<typename R , typename AF >
Future< R > thenR (AF &&func)
 Same as thenR(), but with type defaulted to FutureCallbackType_Auto. More...
 
template<typename R , typename AF , typename Arg0 , typename... Args>
Future< R > thenR (AF &&func, Arg0 &&arg0, Args &&...args)
 
template<typename R , typename AF , typename Arg0 , typename... Args>
Future< R > thenR (FutureCallbackType type, AF &&func, Arg0 &&arg0, Args &&...args)
 
template<typename F >
auto then (FutureCallbackType type, F &&func) -> Future< typename std::result_of< F(Future< T >)>::type >
 Execute a callback when the future is finished. More...
 
template<typename AF >
auto then (AF &&func) -> Future< typename std::result_of< AF(Future< T >)>::type >
 Same as then(), but with type defaulted to FutureCallbackType_Auto. More...
 
template<typename R , typename AF >
Future< R > andThenR (FutureCallbackType type, AF &&func)
 Same as thenR(), but the callback is called only if this future finishes with a value. More...
 
template<typename R , typename AF >
Future< R > andThenR (AF &&func)
 Same as andThenR(), but with type defaulted to FutureCallbackType_Auto. More...
 
template<typename F >
auto andThen (FutureCallbackType type, F &&func) -> Future< typename std::decay< typename std::result_of< F(ValueType)>::type >::type >
 Same as then(), but the callback is called only if this future finishes with a value. More...
 
template<typename AF >
auto andThen (AF &&func) -> Future< typename std::decay< typename std::result_of< AF(ValueType)>::type >::type >
 Same as andThen(), but with type defaulted to FutureCallbackType_Auto. More...
 
boost::function< void()> makeCanceler ()
 Get a functor that will cancel the future. More...
 
template<typename AF >
void connect (const AF &fun, FutureCallbackType type=FutureCallbackType_Auto)
 
template<typename FUNCTYPE , typename ARG0 >
void connect (FUNCTYPE fun, ARG0 tracked,..., FutureCallbackType type=FutureCallbackType_Auto)
 
void connectWithStrand (qi::Strand *strand, const boost::function< void(const Future< T > &)> &cb)
 
void connectWithStrand (qi::Strand &strand, const boost::function< void(const Future< T > &)> &cb)
 
void _connect (const boost::function< void()> &s)
 
template<typename R , typename F >
Future< R > thenRImpl (FutureCallbackType callbackType, F &&continuation)
 
template<typename R , typename F >
Future< R > andThenRImpl (FutureCallbackType callbackType, F &&continuation)
 

Protected Member Functions

boost::shared_ptr
< detail::FutureBaseTyped< T > > 
impl ()
 An accessor to the shared state. TODO: remove it, it should not exist. More...
 
 Future (boost::shared_ptr< detail::FutureBaseTyped< T > > p)
 The constructor from the shared state. More...
 

Protected Attributes

boost::shared_ptr
< detail::FutureBaseTyped< T > > 
_p
 

Friends

class ExecutionContext
 
class Promise< T >
 
class FutureSync< T >
 
class detail::AddUnwrap< T >
 
class ServiceBoundObject
 
template<typename R >
void adaptFutureUnwrap (Future< AnyReference > &f, Promise< R > &p)
 Feed a promise from a generic future which may be unwrapped if it contains itself a future. More...
 
template<typename FT , typename PT >
void adaptFuture (const Future< FT > &f, Promise< PT > &p, AdaptFutureOption option)
 Feed a promise from a future of possibly different type. More...
 
template<typename FT , typename PT , typename CONV >
void adaptFuture (const Future< FT > &f, Promise< PT > &p, CONV converter, AdaptFutureOption option)
 Similar to adaptFuture(f, p) but with a custom converter. More...
 
template<typename R >
void adaptFuture (Future< AnyReference > &f, Promise< R > &p)
 
template<typename FT >
void detail::futureCancelAdapter (boost::weak_ptr< detail::FutureBaseTyped< FT > > wf)
 

Detailed Description

template<typename T>
class qi::Future< T >

Class that represents a value that will be set later in time.

Definition at line 20 of file executioncontext.hpp.

Member Typedef Documentation

template<typename T>
using qi::Future< T >::Connection = boost::function<void(Future<T>)>

Definition at line 533 of file future_fwd.hpp.

template<typename T>
using qi::Future< T >::TemplateValue = T

Definition at line 189 of file future_fwd.hpp.

template<typename T>
using qi::Future< T >::ValueType = typename detail::FutureType<T>::type

Definition at line 187 of file future_fwd.hpp.

template<typename T>
using qi::Future< T >::ValueTypeCast = typename detail::FutureType<T>::typecast

Definition at line 188 of file future_fwd.hpp.

Constructor & Destructor Documentation

template<typename T>
qi::Future< T >::Future ( )
inline

Definition at line 192 of file future_fwd.hpp.

template<typename T>
qi::Future< T >::Future ( const Future< T > &  b)
inline

Definition at line 197 of file future_fwd.hpp.

template<typename T>
qi::Future< T >::Future ( const ValueType v,
FutureCallbackType  async = FutureCallbackType_Auto 
)
inlineexplicit

Construct a Future that already contains a value.

Definition at line 230 of file future_fwd.hpp.

template<typename T>
qi::Future< T >::Future ( boost::shared_ptr< detail::FutureBaseTyped< T > >  p)
inlineprotected

The constructor from the shared state.

Definition at line 591 of file future_fwd.hpp.

Member Function Documentation

template<typename T>
void qi::Future< T >::_connect ( const boost::function< void()> &  s)
inline

Definition at line 578 of file future_fwd.hpp.

template<typename T>
template<typename F >
auto qi::Future< T >::andThen ( FutureCallbackType  type,
F &&  func 
) -> Future<typename std::decay<typename std::result_of<F(ValueType)>::type>::type>
inline

Same as then(), but the callback is called only if this future finishes with a value.

The callback will receive the value of this future, as opposed to this future itself. In the case of Future<void>, the callback shall accept a void* parameter.

If this future finishes with an error or a cancel, the callback will not be called and the returned future will finish in the same state.

Definition at line 506 of file future_fwd.hpp.

template<typename T>
template<typename AF >
auto qi::Future< T >::andThen ( AF &&  func) -> Future<typename std::decay<typename std::result_of<AF(ValueType)>::type>::type>
inline

Same as andThen(), but with type defaulted to FutureCallbackType_Auto.

Definition at line 516 of file future_fwd.hpp.

template<typename T >
template<typename R , typename AF >
Future< R > qi::Future< T >::andThenR ( FutureCallbackType  type,
AF &&  func 
)
inline

Same as thenR(), but the callback is called only if this future finishes with a value.

The callback will receive the value of this future, as opposed to this future itself. In the case of Future<void>, the callback shall accept a void* parameter.

If this future finishes with an error or a cancel, the callback will not be called and the returned future will finish in the same state.

Deprecated:
since 2.5 use andThen()

Definition at line 89 of file future.hxx.

template<typename T>
template<typename R , typename AF >
Future<R> qi::Future< T >::andThenR ( AF &&  func)
inline

Same as andThenR(), but with type defaulted to FutureCallbackType_Auto.

Deprecated:
since 2.5 use andThen()

Definition at line 491 of file future_fwd.hpp.

template<typename T>
template<typename R , typename F >
Future<R> qi::Future< T >::andThenRImpl ( FutureCallbackType  callbackType,
F &&  continuation 
)
inline

Definition at line 96 of file future.hxx.

template<typename T>
void qi::Future< T >::cancel ( )
inline

cancel() the asynchronous operation if possible Exact effect is controlled by the cancel implementation, but it is expected to set a value or an error to the Future as fast as possible. Note that cancelation may be asynchronous.

Definition at line 383 of file future_fwd.hpp.

template<typename T>
template<typename AF >
void qi::Future< T >::connect ( const AF &  fun,
FutureCallbackType  type = FutureCallbackType_Auto 
)
inline

Connect a callback function that will be called once when the Future finishes (that is, switches from running to an other state).

If type is sync, connect may block and call the callback synchronously if the future is already set.

It guaranteed that your callback will be called exactly once (unless the promise is never set or the promise is reset, which is deprecated).

Definition at line 545 of file future_fwd.hpp.

template<typename T>
template<typename FUNCTYPE , typename ARG0 >
void qi::Future< T >::connect ( FUNCTYPE  fun,
ARG0  tracked,
  ...,
FutureCallbackType  type = FutureCallbackType_Auto 
)

Connect a callback with binding and tracking support.

If the first argument is a weak_ptr or a pointer inheriting from qi::Trackable, the callback will not be called if tracked object was destroyed.

template<typename T>
void qi::Future< T >::connectWithStrand ( qi::Strand strand,
const boost::function< void(const Future< T > &)> &  cb 
)
Deprecated:
since 2.5 use the overload with Strand&

Definition at line 126 of file future.hxx.

template<typename T>
void qi::Future< T >::connectWithStrand ( qi::Strand strand,
const boost::function< void(const Future< T > &)> &  cb 
)

Definition at line 133 of file future.hxx.

template<typename T>
const std::string& qi::Future< T >::error ( int  msecs = FutureTimeout_Infinite) const
inline
Parameters
msecs
Returns
the error throw on timeout throw if the future do not have an actual error.

Definition at line 367 of file future_fwd.hpp.

template<typename T>
bool qi::Future< T >::hasError ( int  msecs = FutureTimeout_Infinite) const
inline
Parameters
msecstimeout
Returns
true if the future has an error. throw in the following case:
  • timeout

Definition at line 348 of file future_fwd.hpp.

template<typename T>
bool qi::Future< T >::hasValue ( int  msecs = FutureTimeout_Infinite) const
inline
Parameters
msecstimeout
Returns
true if the future has a value. throw in the following case:
  • timeout

Definition at line 358 of file future_fwd.hpp.

template<typename T>
boost::shared_ptr<detail::FutureBaseTyped<T> > qi::Future< T >::impl ( )
inlineprotected

An accessor to the shared state. TODO: remove it, it should not exist.

Definition at line 588 of file future_fwd.hpp.

template<typename T>
bool qi::Future< T >::isCancelable ( ) const
inline
Returns
always true
Deprecated:
since 2.5

Definition at line 393 of file future_fwd.hpp.

template<typename T>
bool qi::Future< T >::isCanceled ( ) const
inline
Returns
true if the future has been canceled This means that the future has been fully canceled, not that a cancel was requested. do not throw

Definition at line 339 of file future_fwd.hpp.

template<typename T>
bool qi::Future< T >::isFinished ( ) const
inline
Returns
true if the future is finished do not throw

Definition at line 323 of file future_fwd.hpp.

template<typename T>
bool qi::Future< T >::isRunning ( ) const
inline
Returns
true if the future is running do not throw

Definition at line 330 of file future_fwd.hpp.

template<typename T>
bool qi::Future< T >::isValid ( ) const
inline
Returns
true if this future is associated to a promise, false otherwise.

Definition at line 223 of file future_fwd.hpp.

template<typename T >
boost::function< void()> qi::Future< T >::makeCanceler ( )

Get a functor that will cancel the future.

This functor will not keep the future alive, which is useful to avoid reference cycles. If the future does not exist anymore, this is a no-op.

Note
This function should only be useful for bindings, you probably don't need it.

Definition at line 153 of file future.hxx.

template<typename T>
qi::Future< T >::operator const ValueTypeCast & ( ) const
inline

same as value() with an infinite timeout.

Definition at line 289 of file future_fwd.hpp.

template<typename T>
ValueType qi::Future< T >::operator* ( ) const
inline

Return the value associated to a Future.

Note
Equivalent to valueCopy(FutureTimeout_Infinite).

Definition at line 281 of file future_fwd.hpp.

template<typename T>
bool qi::Future< T >::operator< ( const Future< T > &  b) const
inline

Definition at line 212 of file future_fwd.hpp.

template<typename T>
Future<T>& qi::Future< T >::operator= ( const Future< T > &  b)
inline

Definition at line 206 of file future_fwd.hpp.

template<typename T>
bool qi::Future< T >::operator== ( const Future< T > &  other) const
inline

Definition at line 201 of file future_fwd.hpp.

template<typename T>
FutureSync<T> qi::Future< T >::sync ( )
inline

Make the future sync Should not be useful, use wait().

Definition at line 373 of file future_fwd.hpp.

template<typename T>
template<typename F >
auto qi::Future< T >::then ( FutureCallbackType  type,
F &&  func 
) -> Future<typename std::result_of<F(Future<T>)>::type>
inline

Execute a callback when the future is finished.

The callback will receive this future as argument and all other arguments passed to this function.

If the first argument bound to this function is a weak_ptr it will be locked. If it is a Trackable, the callback won't be called after the object's destruction. If it is an Actor, the call will be stranded.

Returns
a future that will receive the value returned by the callback or an error if the callback threw.

Definition at line 453 of file future_fwd.hpp.

template<typename T>
template<typename AF >
auto qi::Future< T >::then ( AF &&  func) -> Future<typename std::result_of<AF(Future<T>)>::type>
inline

Same as then(), but with type defaulted to FutureCallbackType_Auto.

Definition at line 463 of file future_fwd.hpp.

template<typename T >
template<typename R , typename AF >
Future< R > qi::Future< T >::thenR ( FutureCallbackType  type,
AF &&  func 
)
inline

Execute a callback when the future is finished.

The callback will receive this future as argument and all other arguments passed to this function.

If the first argument bound to this function is a weak_ptr it will be locked. If it is a Trackable, the callback won't be called after the object's destruction. If it is an Actor, the call will be stranded.

Template Parameters
Rthe return type of your callback as it is hard to deduce without C++11.
Returns
a future that will receive the value returned by the callback or an error if the callback threw.
Deprecated:
since 2.5 use then()

Definition at line 58 of file future.hxx.

template<typename T>
template<typename R , typename AF >
Future<R> qi::Future< T >::thenR ( AF &&  func)
inline

Same as thenR(), but with type defaulted to FutureCallbackType_Auto.

Deprecated:
since 2.5 use then()

Definition at line 423 of file future_fwd.hpp.

template<typename T >
template<typename R , typename AF , typename Arg0 , typename... Args>
Future< R > qi::Future< T >::thenR ( AF &&  func,
Arg0 &&  arg0,
Args &&...  args 
)
Deprecated:
since 2.5 use then()

Definition at line 1240 of file future_fwd.hpp.

template<typename T >
template<typename R , typename AF , typename Arg0 , typename... Args>
Future< R > qi::Future< T >::thenR ( FutureCallbackType  type,
AF &&  func,
Arg0 &&  arg0,
Args &&...  args 
)
Deprecated:
since 2.5 use then()

Definition at line 1249 of file future_fwd.hpp.

template<typename T>
template<typename R , typename F >
Future<R> qi::Future< T >::thenRImpl ( FutureCallbackType  callbackType,
F &&  continuation 
)
inline

Definition at line 65 of file future.hxx.

template<typename T>
FutureUniqueId qi::Future< T >::uniqueId ( ) const
inline

Definition at line 217 of file future_fwd.hpp.

template<typename T>
const ValueType& qi::Future< T >::value ( int  msecs = FutureTimeout_Infinite) const
inline

Return the value associated to a Future.

Parameters
msecstimeout
Returns
the value

This function can throw for many reason:

  • wait timeout
  • user error
  • future canceled

if an error is set, then value throw a FutureUserException, others errors are FutureException.

Definition at line 249 of file future_fwd.hpp.

template<typename T>
const ValueType& qi::Future< T >::value ( Either< MilliSeconds, Infinity timeout) const
inline

Definition at line 254 of file future_fwd.hpp.

template<typename T>
ValueType qi::Future< T >::valueCopy ( Either< MilliSeconds, Infinity timeout = Infinity{}) const
inline

Return by copy the value associated to a Future.

Definition at line 262 of file future_fwd.hpp.

template<typename T>
boost::shared_ptr<const T> qi::Future< T >::valueSharedPtr ( Either< MilliSeconds, Infinity timeout = Infinity{}) const
inline

Return a shared pointer to the value associated to a Future.

Definition at line 271 of file future_fwd.hpp.

template<typename T>
FutureState qi::Future< T >::wait ( int  msecs = FutureTimeout_Infinite) const
inline

Wait for future to contain a value or an error

Parameters
msecsMaximum time to wait in milliseconds, 0 means return immediately.
Returns
a FutureState corresponding to the state of the future.

Definition at line 296 of file future_fwd.hpp.

template<typename T>
FutureState qi::Future< T >::wait ( qi::Duration  duration) const
inline

Wait for future to contain a value or an error

Parameters
durationMaximum time to wait
Returns
a FutureState corresponding to the state of the future.

Definition at line 303 of file future_fwd.hpp.

template<typename T>
FutureState qi::Future< T >::wait ( qi::SteadyClock::time_point  timepoint) const
inline

Wait for future to contain a value or an error

Parameters
timepointTime until which we can wait
Returns
a FutureState corresponding to the state of the future.

Definition at line 313 of file future_fwd.hpp.

template<typename T>
FutureState qi::Future< T >::waitFor ( qi::Duration  duration) const
inline

Definition at line 306 of file future_fwd.hpp.

template<typename T>
FutureState qi::Future< T >::waitUntil ( qi::SteadyClock::time_point  timepoint) const
inline

Definition at line 316 of file future_fwd.hpp.

Friends And Related Function Documentation

template<typename T>
template<typename FT , typename PT >
void adaptFuture ( const Future< FT > &  f,
Promise< PT > &  p,
AdaptFutureOption  option 
)
friend

Feed a promise from a future of possibly different type.

Will monitor f, and bounce its state to p. Error and canceled state are bounced as is. Valued state is bounced through FutureValueConverter<FT, PT>::convert()

Definition at line 537 of file future.hxx.

template<typename T>
template<typename FT , typename PT , typename CONV >
void adaptFuture ( const Future< FT > &  f,
Promise< PT > &  p,
CONV  converter,
AdaptFutureOption  option 
)
friend

Similar to adaptFuture(f, p) but with a custom converter.

Definition at line 547 of file future.hxx.

template<typename T>
template<typename R >
void adaptFuture ( Future< AnyReference > &  f,
Promise< R > &  p 
)
friend
template<typename T>
template<typename R >
void adaptFutureUnwrap ( Future< AnyReference > &  f,
Promise< R > &  p 
)
friend

Feed a promise from a generic future which may be unwrapped if it contains itself a future.

Definition at line 528 of file future.hxx.

template<typename T>
friend class detail::AddUnwrap< T >
friend

Definition at line 615 of file future_fwd.hpp.

template<typename T>
template<typename FT >
void detail::futureCancelAdapter ( boost::weak_ptr< detail::FutureBaseTyped< FT > >  wf)
friend
template<typename T>
friend class ExecutionContext
friend

Definition at line 584 of file future_fwd.hpp.

template<typename T>
friend class FutureSync< T >
friend

Definition at line 600 of file future_fwd.hpp.

template<typename T>
friend class Promise< T >
friend

Definition at line 599 of file future_fwd.hpp.

template<typename T>
friend class ServiceBoundObject
friend

Definition at line 618 of file future_fwd.hpp.

Member Data Documentation

template<typename T>
boost::shared_ptr< detail::FutureBaseTyped<T> > qi::Future< T >::_p
protected

Definition at line 598 of file future_fwd.hpp.


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