Class template promise

poet::promise — A handle to a promise.

Synopsis

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

  // construct/copy/destruct
  promise();
  promise(const promise &);
  promise& operator=(const promise &);

  // public member functions
  template<typename U> void fulfill(const U &) ;
  template<typename U> void fulfill(const future<U> &) ;
  bool has_future() const;
  void reset();
  void swap(promise &);
  template<typename E> void renege(const E &);
  void renege(const poet::exception_ptr &);
};

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

Description

Promises are used to construct futures and set their values when they become available. You can also renege on a promise, which transports an exception instead of a value to any futures waiting on the promise.

Promise objects are handles with shallow copy semantics. Promises are reference-counted, which means a promise will automatically be reneged with an uncertain_future exception if its reference count drops to zero without the promise being fulfilled.

The idea of making a seperate promise class from the future class was suggested by Chirtopher Kohlhoff. The idea of reference counting the promise class was due to Braddock Gaskill.

`promise` public construct/copy/destruct

```
promise();
```
```
promise(const promise & other);
```
Copy construction creates a shallow copy of other.

promise& operator=(const promise & rhs);

Assignment makes *this a shallow copy of rhs.

`promise` public member functions

```
template<typename U> void fulfill(const U & value) ;
```
Fulfill the promise by giving it a value. All futures which reference this promise will become ready. The type U must be implicitly convertible to the promise's template type T.
```
template<typename U> void fulfill(const future<U> & future_value) ;
```
Chain the promise to another promise by giving it a future. All futures which reference this promise will receive the value from future_value when it becomes ready. If the promise referenced by future_value is broken, this promise will also be broken. The type U must be implicitly convertible to the promise's template type T.

bool has_future() const;

The has_future query allows a promise-fulfilling thread to query if there are any futures left which refer to this promise. This enables a promise-fulfilling thread to exit early if noone is interested in its result.

Returns:

true if there are any future objects in existance which will obtain their value/exception from this promise.

void reset();

Resets the promise by swapping it with a default-constructed promise.

Postconditions:

has_future()==false

```
void swap(promise & other);
```
Swaps *this with other.
```
template<typename E> void renege(const E & exception);
void renege(const poet::exception_ptr & exp);
```
Breaks the promise. Any futures which reference the promise will throw a copy of exception when they attempt to get their value.

`promise` free functions

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

Swaps promises a and b.

Specializations

Class promise<void>