Class template future

poet::future — A placeholder for a future value.

Synopsis

template<typename T> 
class future {
public:
  // types
  typedef T value_type;

  // construct/copy/destruct
  future(const promise<T> &);
  template<typename OtherType> future(const promise<OtherType> &);
  future(const T &);
  template<typename OtherType> future(const OtherType &);
  future(const future &);
  template<typename OtherType> future(const future<OtherType> &);
  future();
  future& operator=(const future &);
  template<typename OtherType> future& operator=(const future<OtherType> &);
  virtual ~future();

  // public member functions
  bool ready() const;
  const T & get() const;
  operator const T &() const;
  void join() const;
  bool timed_join(const boost::system_time &) const;
  bool has_exception() const;
  void swap(future &);
};

// free functions
template<typename T> void swap(future<T> &, future<T> &);

Description

Futures are placeholders for values which may not exist yet. They may be used to conveniently support asyncronous function calls with built-in thread safety. Since a future can be returned before any result is actually ready, an asyncronous call can return a future immediately without blocking the calling thread. The calling thread can then poll the future to determine when a result is ready, or block on the future waiting for a result.

See also

future_barrier: construct a future which becomes ready when all of a group of futures are ready or have an exception.
future_select: construct a future which becomes ready when any of a group of futures is ready or has an exception.

`future` public construct/copy/destruct

```
future(const promise<T> & promise);
```
Creates a new future from a promise. When the promise referenced by promise is fulfilled, the future will become ready.
```
template<typename OtherType> future(const promise<OtherType> & promise);
```
Creates a new future from a promise with a template type OtherType that is implicitly convertible to the future's value_type. When the promise referenced by promise is fulfilled, the future will become ready.
```
future(const T & value);
```
Creates a new future with an initialized value, and provides implicit conversion from a value to the corresponding future.
```
template<typename OtherType> future(const OtherType & value);
```
Creates a new future with an initialized value, and provides implicit conversion from a value to the corresponding future. The OtherType type must be implicitly convertible to T.
```
future(const future & other);
```
Creates a future from another future with an identical template type. The two futures will both reference the same promise.
```
template<typename OtherType> future(const future<OtherType> & other);
```
Creates a future from another future with a compatible template type. *this will indirectly reference the promise or other, obtaining its value by implicit conversion of other's value once it is ready.
```
future();
```
Creates an uncertain future with no promise. An attempt to get an uncertain future's value will throw an uncertain_future exception. An uncertain future may gain promise by assigning it another future with promise.
```
future& operator=(const future & rhs);
```
Assignment from a future with an identical template type results in two futures which share the same promise.
```
template<typename OtherType> future& operator=(const future<OtherType> & rhs);
```
Assignment from a future<U> is supported if U is implicitly convertible to T. The assignment happens immediately, and does not block waiting for other to become ready.
```
virtual ~future();
```

`future` public member functions

bool ready() const;

Returns:

true if the future's value is initialized.

const T & get() const;

get() is used to obtain an initialized value from a future. If the future is not ready, then get() will block until the future's promise is fulfilled or broken. The future's value may also be obtained without an explicit call to get(), through the conversion operator.

Returns:	the future's value.
Throws:	cancelled_future if the conversion fails due to cancellation. If the future's promise is broken, get() will throw whatever exception was specified by the promise::renege() call (subject to the limitations of poet::exception_ptr).

```
operator const T &() const;
```
The conversion operator provides implicit conversions to values. It has the same effects as the explicit get() function.
```
void join() const;
```
join blocks until either ready or has_exception becomes true. Unlike the get method, join will not throw if has_exception is true.

bool timed_join(const boost::system_time & absolute_time) const;

timed_join blocks until absolute_time is reached, or either ready or has_exception becomes true.

Returns:

true if either ready or has_exception return true.

bool has_exception() const;

Returns:

true if this future's promise has been broken. Attempting to get the future's value will throw an exception that may give more information on why the promise was broken.

```
void swap(future & other);
```
Swaps *this with other.

`future` free functions

template<typename T> void swap(future<T> & a, future<T> & b);

Swaps futures a and b.

Specializations

Class future<void>