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 <type_traits>
# include <qi/api.hpp>
# include <qi/assert.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 <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
    {
      using type = T;
      using typecast = T;
    };

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

    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,
    FutureCallbackType_Auto  = 2
  };

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

  enum AdaptFutureOption {
    AdaptFutureOption_None = 0,
    AdaptFutureOption_ForwardCancel = 1,
  };

  using FutureUniqueId = void*;

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

    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> {
    static_assert(!std::is_const<T>::value, "can't create a future of const");
  public:
    using ValueType = typename detail::FutureType<T>::type;
    using ValueTypeCast = typename detail::FutureType<T>::typecast;
    using TemplateValue = T;

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

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

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

    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();
    }

    bool isValid() const
    {
      return _p->state() != FutureState_None;
    }

    explicit Future<T>(const ValueType& v, FutureCallbackType async = FutureCallbackType_Auto)
    {
      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);
    }

    QI_API_DEPRECATED_MSG("Method implementation removed, always returns 'true'")
    bool isCancelable() const
    {
      return true;
    }

    template <typename R, typename AF>
    QI_API_DEPRECATED_MSG(Use 'then' instead)
    Future<R> thenR(FutureCallbackType type, AF&& func);

    template <typename R, typename AF>
    QI_API_DEPRECATED_MSG(Use 'then' instead)
    Future<R> thenR(AF&& func)
    {
      return thenRImpl<R>(FutureCallbackType_Auto, std::forward<AF>(func));
    }

    template <typename R, typename AF, typename Arg0, typename... Args>
    QI_API_DEPRECATED_MSG(Use 'then' instead)
    Future<R> thenR(AF&& func, Arg0&& arg0, Args&&... args)
    {
      return thenRImpl<R>(
          FutureCallbackType_Auto,
          qi::bind(std::forward<AF>(func), std::forward<Arg0>(arg0), std::forward<Args>(args)...));
    }

    template <typename R, typename AF, typename Arg0, typename... Args>
    QI_API_DEPRECATED_MSG(Use 'then' instead)
    Future<R> thenR(FutureCallbackType type, AF&& func, Arg0&& arg0, Args&&... args)
    {
      return thenRImpl<R>(
          type,
          qi::bind(std::forward<AF>(func), arg0, std::forward<Args>(args)...));
    }

    template <typename AF>
    auto then(FutureCallbackType type, AF&& func)
        -> qi::Future<typename detail::DecayAsyncResult<AF, qi::Future<T>>::type>
    {
      return thenRImpl<typename detail::DecayAsyncResult<AF, qi::Future<T>>::type>(type, std::forward<AF>(func));
    }

    template <typename AF>
    auto then(AF&& func)
        -> qi::Future<typename detail::DecayAsyncResult<AF, qi::Future<T>>::type>
    {
      return this->then(FutureCallbackType_Auto, std::forward<AF>(func));
    }

    template <typename R, typename AF>
    QI_API_DEPRECATED_MSG(Use 'andThen' instead)
    Future<R> andThenR(FutureCallbackType type, AF&& func);

    template <typename R, typename AF>
    QI_API_DEPRECATED_MSG(Use 'andThen' instead)
    Future<R> andThenR(AF&& func)
    {
      return andThenRImpl<R>(FutureCallbackType_Auto, std::forward<AF>(func));
    }

    template <typename AF>
    auto andThen(FutureCallbackType type, AF&& func)
        -> qi::Future<typename detail::DecayAsyncResult<AF, ValueType>::type>
    {
      return this->andThenRImpl<typename detail::DecayAsyncResult<AF, ValueType>::type>(type, std::forward<AF>(func));
    }

    template <typename AF>
    auto andThen(AF&& func)
        -> qi::Future<typename detail::DecayAsyncResult<AF, ValueType>::type>
    {
      return this->andThen(FutureCallbackType_Auto, std::forward<AF>(func));
    }

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

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

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

    template<typename FUNCTYPE, typename ARG0>
    void connect(FUNCTYPE fun, ARG0 tracked, ...,
                 FutureCallbackType type = FutureCallbackType_Auto);
#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_Auto) \
  {                                                                      \
    this->then(type, qi::bind(fun, arg0 comma AUSE));                    \
  }
    QI_GEN(genCall)
#undef genCall
#endif

    // @deprecated since 2.5 use the overload with Strand&
    QI_API_DEPRECATED_MSG(Use overload with 'Strand&' instead)
    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);

    // 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)
    {
      QI_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, AdaptFutureOption option);
    template<typename FT, typename PT, typename CONV>
    friend void adaptFuture(const Future<FT>& f, Promise<PT>& p,
                            CONV converter, AdaptFutureOption option);
    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;
    // Private forward impl to then
    template <typename R, typename AF>
    Future<R> andThenRImpl(FutureCallbackType type, AF&& func);

    // Private forward impl to then
    template <typename R, typename AF>
    Future<R> thenRImpl(FutureCallbackType type, AF&& func);

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

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

  template<typename T>
  class FutureSync
  {
  public:
    using ValueType = typename Future<T>::ValueType;
    using ValueTypeCast = typename Future<T>::ValueTypeCast;
    using Connection = typename Future<T>::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 isValid() const                                               { _sync = false; return _future.isValid(); }
    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 true; }
    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:
    using ValueType = typename detail::FutureType<T>::type;

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

    template <typename FUNC,
              typename std::enable_if<!std::is_same<
                                        typename std::decay<FUNC>::type,
                                        typename std::decay<qi::Promise<T> >::type
                                        >::value
                                      >::type* = nullptr>
    explicit Promise(FUNC&& cancelCallback,
        FutureCallbackType async = FutureCallbackType_Auto)
    {
      setup(std::forward<FUNC>(cancelCallback), async);
      ++_f._p->_promiseCount;
    }

    explicit Promise(boost::function<void (qi::Promise<T>)> cancelCallback,
        FutureCallbackType async = FutureCallbackType_Auto)
    {
      setup([cancelCallback](qi::Promise<T>& p){ cancelCallback(p); }, 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)
    {
      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_Auto)
    {
      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, AdaptFutureOption option);
    template<typename FT, typename PT, typename CONV>
    friend void adaptFuture(const Future<FT>& f, Promise<PT>& p,
                            CONV converter, AdaptFutureOption option);
    template<typename R>
    friend void adaptFuture(Future<AnyReference>& f, Promise<R>& p);

  private:
    void decRefcnt()
    {
      QI_ASSERT(_f._p->_promiseCount.load() > 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);
    }
  };

  namespace detail
  {
    class FutureBasePrivate;
    class QI_API FutureBase {
    public:
      FutureBase();
      ~FutureBase();

      FutureState wait(int msecs) const;
      FutureState wait(qi::Duration duration) const;
      FutureState wait(qi::SteadyClock::time_point timepoint) const;
      FutureState state() const;
      bool isRunning() const;
      bool isFinished() const;
      bool isCanceled() const;
      bool isCancelRequested() const;
      bool hasError(int msecs) const;
      bool hasValue(int msecs) const;
      const std::string &error(int msecs) const;
      void reportStart();

    protected:
      void reportValue();
      void reportError(const std::string &message);
      void requestCancel();
      void reportCanceled();
      boost::recursive_mutex& mutex();
      void notifyFinish();

    public:
      FutureBasePrivate *_p;
    };


    //common state shared between a Promise and multiple Futures
    template <typename T>
    class FutureBaseTyped : public FutureBase {
    public:
      using CancelCallback = boost::function<void(Promise<T>&)>;
      using ValueType = typename FutureType<T>::type;
      FutureBaseTyped();
      ~FutureBaseTyped();

      void cancel(qi::Future<T>& future);

      void callCbNotify(qi::Future<T>& future);

      /*
       * inplace api for promise
       */
      void set(qi::Future<T>& future);
      void setValue(qi::Future<T>& future, const ValueType &value);
      void setError(qi::Future<T>& future, const std::string &message);
      void setBroken(qi::Future<T>& future);
      void setCanceled(qi::Future<T>& future);

      void setOnCancel(qi::Promise<T>& promise, CancelCallback onCancel);
      void setOnDestroyed(boost::function<void (ValueType)> f);

      void connect(qi::Future<T> future,
          const boost::function<void (qi::Future<T>)> &s,
          FutureCallbackType type);

      const ValueType& value(int msecs) const;

    private:
      friend class Promise<T>;
      using CallbackType = boost::function<void(qi::Future<T>)>;
      struct Callback
      {
        CallbackType callback;
        FutureCallbackType callType;

        Callback(CallbackType callback, FutureCallbackType callType)
          : callback(callback)
          , callType(callType)
        {}
      };
      using Callbacks = std::vector<Callback>;
      Callbacks                _onResult;
      ValueType                _value;
      CancelCallback           _onCancel;
      boost::function<void (ValueType)> _onDestroyed;
      FutureCallbackType       _async;
      qi::Atomic<unsigned int> _promiseCount;

      void clearCallbacks();
    };
  }

  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, AdaptFutureOption option = AdaptFutureOption_ForwardCancel);

  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,
      AdaptFutureOption option = AdaptFutureOption_ForwardCancel);

  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_