future.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 <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 {

  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 FutureInterface;
  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,
  };

  class QI_API FutureException : public std::runtime_error {
  public:
    enum ExceptionState {
      //No result ready
      ExceptionState_FutureTimeout,
      //The future has been canceled
      ExceptionState_FutureCanceled,
      //The future is not cancelable
      ExceptionState_FutureNotCancelable,
      //asked for error, but there is no error
      ExceptionState_FutureHasNoError,
      //real future error
      ExceptionState_FutureUserError,
      //when the promise is already set.
      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:
    typedef typename FutureType<T>::type     ValueType;
    typedef typename 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();
    }
    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 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();
    }
  public: //Signals
    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)                 \
    {                                                                       \
      _p->connect(*this, ::qi::bind<void(Future<T>)>(fun, arg0 comma AUSE), \
          type);                                                            \
    }
    QI_GEN(genCall)
#undef genCall
#endif

    // 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 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 FT>
    friend void detail::futureCancelAdapter(
        boost::weak_ptr<detail::FutureBaseTyped<FT> > wf);
  };



  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()
    {
      if (_sync)
        _future.value();
    }

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

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

    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); }
    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 FutureType<T>::type ValueType;

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

    explicit Promise(boost::function<void (qi::Promise<T>)> cancelCallback, FutureCallbackType async = FutureCallbackType_Async)
    {
      setup(cancelCallback, async);
    }

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

    /* reset the promise and the future */
    void reset() {
      _f._p->reset();
    }

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

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

    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 T>
  class FutureBarrier {
  public:
    FutureBarrier(FutureCallbackType async = FutureCallbackType_Async)
      : _closed(false)
      , _count(0)
      , _futures()
      , _promise(async)
    {}

    bool addFuture(qi::Future<T> fut) {
      // Can't add future from closed qi::FutureBarrier.
      if (this->_closed)
        return false;

      ++(this->_count);
      fut.connect(boost::bind<void>(&FutureBarrier::onFutureFinish, this));
      this->_futures.push_back(fut);
      return true;
    }

    Future< std::vector< Future<T> > > future() {
      this->close();
      return this->_promise.future();
    }

  protected:
    bool _closed;
    Atomic<int> _count;
    std::vector< Future<T> > _futures;
    Promise< std::vector< Future<T> > > _promise;

  private:
    void onFutureFinish() {
      if (--(this->_count) == 0 && this->_closed) {
        this->_promise.setValue(this->_futures);
      }
    }

    void close() {
      this->_closed = true;
      if (*(this->_count) == 0) {
        this->_promise.setValue(this->_futures);
      }
    }
  };

  template <typename T>
  qi::Future<T> makeFutureError(const std::string &value, FutureCallbackType async = FutureCallbackType_Async);

  template <typename T>
  void waitForAll(std::vector< Future<T> >& vect);

  template <typename T>
  qi::FutureSync< qi::Future<T> > waitForFirst(std::vector< Future<T> >& vect);

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

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

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

#ifdef _MSC_VER
#  pragma warning( pop )
#endif

#include <qi/details/future.hxx>

#endif  // _QI_FUTURE_HPP_