libqi-api  release-2.5.3-2016-11-18
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Types | Public 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...
 
 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 AF >
auto then (FutureCallbackType type, AF &&func) -> qi::Future< typename detail::DecayAsyncResult< AF, qi::Future< T >>::type >
 Execute a callback when the future is finished. More...
 
template<typename AF >
auto then (AF &&func) -> qi::Future< typename detail::DecayAsyncResult< AF, qi::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 AF >
auto andThen (FutureCallbackType type, AF &&func) -> qi::Future< typename detail::DecayAsyncResult< AF, ValueType >::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) -> qi::Future< typename detail::DecayAsyncResult< AF, ValueType >::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)
 
boost::shared_ptr
< detail::FutureBaseTyped< T > > 
impl ()
 
 Future (boost::shared_ptr< detail::FutureBaseTyped< T > > p)
 

Protected Attributes

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

Friends

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 19 of file executioncontext.hpp.

Member Typedef Documentation

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

Definition at line 472 of file future_fwd.hpp.

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

Definition at line 154 of file future_fwd.hpp.

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

Definition at line 152 of file future_fwd.hpp.

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

Definition at line 153 of file future_fwd.hpp.

Constructor & Destructor Documentation

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

Definition at line 157 of file future_fwd.hpp.

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

Definition at line 162 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 195 of file future_fwd.hpp.

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

Definition at line 525 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 519 of file future_fwd.hpp.

template<typename T>
template<typename AF >
auto qi::Future< T >::andThen ( FutureCallbackType  type,
AF &&  func 
) -> qi::Future<typename detail::DecayAsyncResult<AF, ValueType>::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.

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 445 of file future_fwd.hpp.

template<typename T>
template<typename AF >
auto qi::Future< T >::andThen ( AF &&  func) -> qi::Future<typename detail::DecayAsyncResult<AF, ValueType>::type>
inline

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

Definition at line 455 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.

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 238 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 431 of file future_fwd.hpp.

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.

Exceptions
ExceptionState_FutureNotCancelableif isCancelable() is false.

Definition at line 314 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 484 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 
)

Definition at line 275 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 282 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 297 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 278 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 288 of file future_fwd.hpp.

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

Definition at line 524 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 324 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 269 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 253 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 260 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 188 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 302 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 219 of file future_fwd.hpp.

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

Definition at line 177 of file future_fwd.hpp.

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

Definition at line 171 of file future_fwd.hpp.

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

Definition at line 166 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 303 of file future_fwd.hpp.

template<typename T>
template<typename AF >
auto qi::Future< T >::then ( FutureCallbackType  type,
AF &&  func 
) -> qi::Future<typename detail::DecayAsyncResult<AF, qi::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 394 of file future_fwd.hpp.

template<typename T>
template<typename AF >
auto qi::Future< T >::then ( AF &&  func) -> qi::Future<typename detail::DecayAsyncResult<AF, qi::Future<T>>::type>
inline

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

Definition at line 404 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 199 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 354 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 
)
inline
Deprecated:
since 2.5 use then()

Definition at line 364 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 
)
inline
Deprecated:
since 2.5 use then()

Definition at line 376 of file future_fwd.hpp.

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

Definition at line 182 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 214 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 226 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 233 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 243 of file future_fwd.hpp.

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

Definition at line 236 of file future_fwd.hpp.

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

Definition at line 246 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 673 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 683 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 663 of file future.hxx.

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

Definition at line 550 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 FutureSync< T >
friend

Definition at line 535 of file future_fwd.hpp.

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

Definition at line 534 of file future_fwd.hpp.

template<typename T>
friend class ServiceBoundObject
friend

Definition at line 553 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 533 of file future_fwd.hpp.


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