future_fwd.hpp

Go to the documentation of this file.

#pragma once
/*
**  Copyright (C) 2012 Aldebaran Robotics
**  See COPYING for the license
*/

#ifndef _QI_FUTURE_HPP_
# define _QI_FUTURE_HPP_

# include <qi/api.hpp>
# include <vector>
# include <qi/atomic.hpp>
# include <qi/config.hpp>
# include <qi/trackable.hpp>
# include <qi/clock.hpp>
# include <qi/detail/mpl.hpp>
# include <qi/anyvalue.hpp>

# include <boost/shared_ptr.hpp>
# include <boost/make_shared.hpp>
# include <boost/function.hpp>
# include <boost/bind.hpp>
# include <boost/thread/recursive_mutex.hpp>

# ifdef _MSC_VER
#   pragma warning( push )
#   pragma warning( disable: 4251 )
#   pragma warning( disable: 4275 ) //std::runtime_error: no dll interface
# endif

namespace qi {

  class AnyReference;

  namespace detail
  {
    template<typename T>
    struct FutureType
    {
      typedef T type;
      typedef T typecast;
    };

    struct FutureHasNoValue {};
    // Hold a void* for Future<void>
    template<>
    struct FutureType<void>
    {
      typedef void* type;
      typedef FutureHasNoValue typecast;
    };

    template <typename T>
    class AddUnwrap
    {};
  }

  class Actor;
  class Strand;

  template <typename T> class Future;
  template <typename T> class FutureSync;
  template <typename T> class Promise;

  namespace detail {
    template <typename T> class FutureBaseTyped;

    template<typename FT>
    void futureCancelAdapter(
                             boost::weak_ptr<detail::FutureBaseTyped<FT> > wf);
  }

  enum FutureState {
    FutureState_None,               
    FutureState_Running,            
    FutureState_Canceled,           
    FutureState_FinishedWithError,  
    FutureState_FinishedWithValue,  
  };

  enum FutureCallbackType {
    FutureCallbackType_Sync  = 0,
    FutureCallbackType_Async = 1
  };

  enum FutureTimeout {
    FutureTimeout_Infinite = ((int) 0x7fffffff),
    FutureTimeout_None     = 0,
  };

  typedef void* FutureUniqueId;

  class QI_API FutureException : public std::runtime_error {
  public:
    enum ExceptionState {
      ExceptionState_FutureTimeout,       
      ExceptionState_FutureCanceled,      
      ExceptionState_FutureNotCancelable, 
      ExceptionState_FutureHasNoError,    
      ExceptionState_FutureUserError,     
      ExceptionState_PromiseAlreadySet,   
    };

    explicit FutureException(const ExceptionState &es, const std::string &str = std::string())
      : std::runtime_error(stateToString(es) + str)
      , _state(es)
    {}

    inline ExceptionState state() const { return _state; }

    std::string stateToString(const ExceptionState &es);

    virtual ~FutureException() throw()
    {}

  private:
    ExceptionState _state;
  };

  class QI_API FutureUserException : public FutureException {
  public:

    explicit FutureUserException(const std::string &str = std::string())
      : FutureException(ExceptionState_FutureUserError, str)
    {}

    virtual ~FutureUserException() throw()
    {}
  };

  template <typename T>
  class Future : public detail::AddUnwrap<T> {
  public:
    typedef typename detail::FutureType<T>::type     ValueType;
    typedef typename detail::FutureType<T>::typecast ValueTypeCast;

  public:
    Future()
      : _p(boost::make_shared<detail::FutureBaseTyped<T> >())
    {
    }

    Future(const Future<T>& b)
      : _p(b._p)
    {}

    bool operator==(const Future<T> &other)
    {
      return _p.get() == other._p.get();
    }

    inline Future<T>& operator=(const Future<T>& b)
    {
      _p = b._p;
      return *this;
    }

    bool operator < (const Future<T>& b) const
    {
      return _p.get() < b._p.get();
    }

    FutureUniqueId uniqueId() const
    {
      return _p.get();
    }

    explicit Future<T>(const ValueType& v, FutureCallbackType async = FutureCallbackType_Async)
    {
      Promise<T> promise(async);
      promise.setValue(v);
      *this = promise.future();
    }

    inline const ValueType &value(int msecs = FutureTimeout_Infinite) const
    { return _p->value(msecs); }

    inline operator const ValueTypeCast&() const
    { return _p->value(FutureTimeout_Infinite); }

    inline FutureState wait(int msecs = FutureTimeout_Infinite) const
    { return _p->wait(msecs); }

    inline FutureState wait(qi::Duration duration) const
    { return _p->wait(duration); }

    inline FutureState waitFor(qi::Duration duration) const
    { return this->wait(duration); }

    inline FutureState wait(qi::SteadyClock::time_point timepoint) const
    { return _p->wait(timepoint); }

    inline FutureState waitUntil(qi::SteadyClock::time_point timepoint) const
    { return this->wait(timepoint); }

    inline bool isFinished() const
    { return _p->isFinished(); }

    inline bool isRunning() const
    { return _p->isRunning(); }

    inline bool isCanceled() const
    { return _p->isCanceled(); }

    inline bool hasError(int msecs = FutureTimeout_Infinite) const
    { return _p->hasError(msecs); }

    inline bool hasValue(int msecs = FutureTimeout_Infinite) const
    { return _p->hasValue(msecs); }

    inline const std::string &error(int msecs = FutureTimeout_Infinite) const
    { return _p->error(msecs); }

    inline FutureSync<T> sync()
    {
      return FutureSync<T>(*this);
    };

    void cancel()
    {
      _p->cancel(*this);
    }

    bool isCancelable() const
    {
      return _p->isCancelable();
    }

    template <typename R>
    Future<R> thenR(
        FutureCallbackType type,
        const boost::function<R(const Future<T>&)>& func);

    template <typename R>
    Future<R> thenR(
        const boost::function<R(const Future<T>&)>& func)
    {
      return this->thenR(FutureCallbackType_Async, func);
    }

    template <typename R>
    Future<R> andThenR(
        FutureCallbackType type,
        const boost::function<R(const typename Future<T>::ValueType&)>& func);

    template <typename R>
    Future<R> andThenR(
        const boost::function<R(const typename Future<T>::ValueType&)>& func)
    {
      return this->andThenR(FutureCallbackType_Async, func);
    }

#define genCall(n, ATYPEDECL, ATYPES, ADECL, AUSE, comma)                    \
  template <typename R, typename AF, typename ARG0 comma ATYPEDECL>          \
  Future<R> thenR(const AF& func, const ARG0& arg0 comma ADECL)              \
  {                                                                          \
    return this->thenR<R>(FutureCallbackType_Async, func, arg0 comma AUSE);  \
  }                                                                          \
  template <typename R, typename AF, typename ARG0 comma ATYPEDECL>          \
  Future<R> thenR(FutureCallbackType type, const AF& func,                   \
                  const ARG0& arg0 comma ADECL)                              \
  {                                                                          \
    return _thenMaybeActor<R, ARG0>(                                         \
        arg0, ::qi::bind<R(const Future<T>&)>(func, arg0 comma AUSE), type); \
  }
    QI_GEN(genCall)
#undef genCall

    boost::function<void()> makeCanceler();

  public:
    typedef boost::function<void (Future<T>) > Connection;

    template<typename AF>
    inline void connect(const AF& fun,
                        FutureCallbackType type = FutureCallbackType_Async)
    {
      _p->connect(*this, fun, type);
    }
#ifdef DOXYGEN

    template<typename FUNCTYPE, typename ARG0>
    void connect(FUNCTYPE fun, ARG0 tracked, ...,
                 FutureCallbackType type = FutureCallbackType_Async);
#else
#define genCall(n, ATYPEDECL, ATYPES, ADECL, AUSE, comma)                 \
  template <typename AF, typename ARG0 comma ATYPEDECL>                   \
  inline void connect(const AF& fun, const ARG0& arg0 comma ADECL,        \
                      FutureCallbackType type = FutureCallbackType_Async) \
  {                                                                       \
    _connectMaybeActor<ARG0>(                                             \
        arg0, ::qi::bind<void(Future<T>)>(fun, arg0 comma AUSE), type);   \
  }
    QI_GEN(genCall)
#undef genCall
#endif

    inline void connectWithStrand(qi::Strand* strand,
        const boost::function<void(const Future<T>&)>& cb)
    {
      _p->connect(
          *this,
          transformStrandedCallback(strand, cb),
          FutureCallbackType_Sync);
    }

    // Our companion library libqitype requires a connect with same signature for all instantiations
    inline void _connect(const boost::function<void()>& s)
    {
      connect(boost::bind(s));
    }

    boost::shared_ptr<detail::FutureBaseTyped<T> > impl() { return _p;}
    Future(boost::shared_ptr<detail::FutureBaseTyped<T> > p) :
      _p(p)
    {
      assert(_p);
    }

  protected:
    // C4251 needs to have dll-interface to be used by clients of class 'qi::Future<T>'
    boost::shared_ptr< detail::FutureBaseTyped<T> > _p;
    friend class Promise<T>;
    friend class FutureSync<T>;

    template<typename R>
    friend void adaptFutureUnwrap(Future<AnyReference>& f, Promise<R>& p);
    template<typename FT, typename PT>
    friend void adaptFuture(const Future<FT>& f, Promise<PT>& p);
    template<typename FT, typename PT, typename CONV>
    friend void adaptFuture(const Future<FT>& f, Promise<PT>& p,
                            CONV converter);
    template<typename R>
    friend void adaptFuture(Future<AnyReference>& f, Promise<R>& p);

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

  private:
    friend class ServiceBoundObject;

    // Nuke this when C++03 ends
    void setOnDestroyed(boost::function<void(ValueType)> cb)
    {
      _p->setOnDestroyed(cb);
    }

    template <typename Arg>
    static void binder(
        const boost::function<void(const boost::function<void()>&)>& poster,
        const boost::function<void(const Arg&)>& callback, const Arg& fut);

    template <typename Arg>
    boost::function<void(const Arg&)> transformStrandedCallback(
        qi::Strand* strand,
        const boost::function<void(const Arg&)>& cb);

    template <typename ARG0>
    typename boost::enable_if<
        boost::is_base_of<Actor, typename detail::Unwrap<ARG0>::type>,
        void>::type
        _connectMaybeActor(const ARG0& arg0,
                           const boost::function<void(const Future<T>&)>& cb,
                           FutureCallbackType type);
    template <typename ARG0>
    typename boost::disable_if<
        boost::is_base_of<Actor, typename detail::Unwrap<ARG0>::type>,
        void>::type
        _connectMaybeActor(const ARG0& arg0,
                           const boost::function<void(const Future<T>&)>& cb,
                           FutureCallbackType type);

    template <typename R>
    static void _continuate(const Future<T>& future,
        const boost::function<R(const Future<T>&)>& func,
        Promise<R>& promise);

    static void _cancelContinuation(const Future<T>& future,
        Promise<T>& promise);

    template <typename R, typename ARG0, typename AF>
    typename boost::enable_if<
        boost::is_base_of<Actor, typename detail::Unwrap<ARG0>::type>,
        qi::Future<R> >::type
        _thenMaybeActor(const ARG0& arg0,
            const AF& cb,
            FutureCallbackType type);
    template <typename R, typename ARG0, typename AF>
    typename boost::disable_if<
        boost::is_base_of<Actor, typename detail::Unwrap<ARG0>::type>,
        qi::Future<R> >::type
        _thenMaybeActor(const ARG0& arg0,
            const AF& cb,
            FutureCallbackType type);

    static void _weakCancelCb(const boost::weak_ptr<detail::FutureBaseTyped<T> >& wfuture);
  };

  template<typename T>
  class FutureSync
  {
  public:
    typedef typename Future<T>::ValueType ValueType;
    typedef typename Future<T>::ValueTypeCast ValueTypeCast;
    typedef typename Future<T>::Connection Connection;
    // This future cannot be set, so sync starts at false
    FutureSync() : _sync(false) {}

    FutureSync(const Future<T>& b)
      : _sync(true)
    {
      _future = b;
    }

    FutureSync(const FutureSync<T>& b)
      : _sync(true)
    {
      _future = b._future;
      b._sync = false;
    }

    explicit FutureSync<T>(const ValueType& v)
    : _sync(false)
    {
      Promise<T> promise;
      promise.setValue(v);
      _future = promise.future();
    }

    inline FutureSync<T>& operator=(const FutureSync<T>& b)
    {
      _future = b;
      _sync = true;
      b._sync = false;
      return *this;
    }

    inline FutureSync<T>& operator=(const Future<T>& b)
    {
      _future = b;
      _sync = true;
      return *this;
    }

    ~FutureSync() QI_NOEXCEPT(false)
    {
      if (_sync)
        _future.value();
    }

    operator Future<T>()
    {
      return async();
    }

    bool operator < (const FutureSync<T>& b) const
    {
      return _future._p.get() < b._future._p.get();
    }

    FutureUniqueId uniqueId() const
    {
      return _future.uniqueId();
    }

    const ValueType &value(int msecs = FutureTimeout_Infinite) const   { _sync = false; return _future.value(msecs); }
    operator const typename Future<T>::ValueTypeCast&() const          { _sync = false; return _future.value(); }
    FutureState wait(int msecs = FutureTimeout_Infinite) const         { _sync = false; return _future.wait(msecs); }
    FutureState wait(qi::Duration duration) const                      { _sync = false; return _future.wait(duration); }
    FutureState waitFor(qi::Duration duration) const                   { _sync = false; return _future.waitFor(duration); }
    FutureState wait(qi::SteadyClock::time_point timepoint) const      { _sync = false; return _future.wait(timepoint); }
    FutureState waitUntil(qi::SteadyClock::time_point timepoint) const { _sync = false; return _future.waitUntil(timepoint); }
    bool isRunning() const                                             { _sync = false; return _future.isRunning(); }
    bool isFinished() const                                            { _sync = false; return _future.isFinished(); }
    bool isCanceled() const                                            { _sync = false; return _future.isCanceled(); }
    bool hasError(int msecs = FutureTimeout_Infinite) const            { _sync = false; return _future.hasError(msecs); }
    bool hasValue(int msecs = FutureTimeout_Infinite) const            { _sync = false; return _future.hasValue(msecs); }
    const std::string &error(int msecs = FutureTimeout_Infinite) const { _sync = false; return _future.error(msecs); }
    void cancel()                                                      { _sync = false; _future.cancel(); }
    bool isCancelable() const                                          { _sync = false; return _future.isCancelable(); }
    void connect(const Connection& s)                                  { _sync = false; _future.connect(s);}
    void _connect(const boost::function<void()>& s)                    { _sync = false; _future._connect(s);}

#ifdef DOXYGEN

    template<typename FUNCTYPE, typename ARG0>
    void connect(FUNCTYPE fun, ARG0 tracked, ...);
#else
#define genCall(n, ATYPEDECL, ATYPES, ADECL, AUSE, comma)               \
    template<typename AF, typename ARG0 comma ATYPEDECL>                \
    inline void connect(const AF& fun, const ARG0& arg0 comma ADECL)    \
    {                                                                   \
      _sync = false;                                                    \
      connect(::qi::bind<void(FutureSync<T>)>(fun, arg0 comma AUSE));   \
    }
    QI_GEN(genCall)
#undef genCall
#endif

    Future<T> async()
    {
      _sync = false;
      return _future;
    }

  protected:
    mutable bool _sync;
    Future<T> _future;
    friend class Future<T>;
  };

  template <typename T>
  class Promise {
  public:
    typedef typename detail::FutureType<T>::type ValueType;

    explicit Promise(FutureCallbackType async = FutureCallbackType_Async) {
      _f._p->reportStart();
      _f._p->_async = async;
      ++_f._p->_promiseCount;
    }

    explicit Promise(boost::function<void (qi::Promise<T>)> cancelCallback,
        FutureCallbackType async = FutureCallbackType_Async)
    {
      setup(cancelCallback, async);
      ++_f._p->_promiseCount;
    }

    Promise(const qi::Promise<T>& rhs)
    {
      _f = rhs._f;
      ++_f._p->_promiseCount;
    }

    ~Promise() {
      decRefcnt();
    }

    void setValue(const ValueType &value) {
      _f._p->setValue(_f, value);
    }

    void setError(const std::string &msg) {
      _f._p->setError(_f, msg);
    }

    void setCanceled() {
      _f._p->setCanceled(_f);
    }

    bool isCancelRequested() const {
      return _f._p->isCancelRequested();
    }

    Future<T> future() const { return _f; }

    ValueType& value() { return _f._p->_value;}
    void trigger() { _f._p->set(_f);}

    void setOnCancel(boost::function<void (qi::Promise<T>)> cancelCallback)
    {
      if (!this->_f._p->isCancelable())
        throw std::runtime_error("Promise was not created as a cancelable one");
      qi::Future<T> fut = this->future();
      this->_f._p->setOnCancel(*this, cancelCallback);
    }

    Promise<T>& operator=(const Promise<T>& rhs)
    {
      if (_f._p == rhs._f._p)
        return *this;

      decRefcnt();
      _f = rhs._f;
      ++_f._p->_promiseCount;
      return *this;
    }

  protected:
    void setup(boost::function<void (qi::Promise<T>)> cancelCallback, FutureCallbackType async = FutureCallbackType_Async)
    {
      this->_f._p->reportStart();
      this->_f._p->setOnCancel(*this, cancelCallback);
      this->_f._p->_async = async;
    }
    explicit Promise(Future<T>& f) : _f(f) {
      ++_f._p->_promiseCount;
    }
    template<typename> friend class ::qi::detail::FutureBaseTyped;
    Future<T> _f;

    template<typename R>
    friend void adaptFutureUnwrap(Future<AnyReference>& f, Promise<R>& p);
    template<typename FT, typename PT>
    friend void adaptFuture(const Future<FT>& f, Promise<PT>& p);
    template<typename FT, typename PT, typename CONV>
    friend void adaptFuture(const Future<FT>& f, Promise<PT>& p,
                            CONV converter);
    template<typename R>
    friend void adaptFuture(Future<AnyReference>& f, Promise<R>& p);

  private:
    void decRefcnt()
    {
      assert(*_f._p->_promiseCount > 0);
      // this is race-free because if we reach 0 it means that this is the last Promise pointing to a state and since it
      // is the last, no one could be trying to make a copy from it while destroying it. Also no one could be changing
      // the promise state (from running to finished or whatever) while destroying it.
      if (--_f._p->_promiseCount == 0 && _f.isRunning())
        _f._p->setBroken(_f);
    }
  };

  template <typename T>
  qi::Future<T> makeFutureError(const std::string& error);

  template <typename T>
  void PromiseNoop(qi::Promise<T>&)
  {
  }

  template<typename FT, typename PT>
  struct FutureValueConverter
  {
    void operator()(const FT& vIn, PT& vOut) { vOut = vIn;}
  };

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

  template<typename FT, typename PT>
  void adaptFuture(const Future<FT>& f, Promise<PT>& p);

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

  template<typename FT, typename PT, typename CONV>
  void adaptFuture(const Future<FT>& f, Promise<PT>& p, CONV converter);

  template <typename T>
  inline boost::function<void()> makeCanceler(Future<T>& future)
  {
    return future.makeCanceler();
  }
}

#ifdef _MSC_VER
#  pragma warning( pop )
#endif

#endif  // _QI_FUTURE_HPP_