| Home | Libraries | People | FAQ | More

#### Template `promise<>`

A `promise<>` provides a mechanism to store a value (or exception) that can later be retrieved from the corresponding `future<>` object. `promise<>` and `future<>` communicate via their underlying shared state.

    #include <boost/fiber/future/promise.hpp>

    namespace boost {
    namespace fibers {

    template< typename R >
    class promise {
    public:
        promise();

        template< typename Allocator >
        promise( std::allocator_arg_t, Allocator);

        promise( promise &&) noexcept;

        promise & operator=( promise &&) noexcept;

        promise( promise const&) = delete;

        promise & operator=( promise const&) = delete;

        ~promise();

        void swap( promise &) noexcept;

        future< R > get_future();

        void set_value( R const&);  // member only of generic promise template
        void set_value( R &&);      // member only of generic promise template
        void set_value( R &);       // member only of promise< R & > template
        void set_value();           // member only of promise< void > template

        void set_exception( std::exception_ptr p);
    };

    template< typename R >
    void swap( promise< R > &, promise< R > &) noexcept;

    }

###### Default constructor

    promise();

Effects:

  Creates a promise with an empty shared state.

Throws:

  Exceptions caused by memory allocation.

###### Constructor

    template< typename Allocator >
    promise( std::allocator_arg_t, Allocator alloc);

Effects:

  Creates a promise with an empty shared state by using `alloc`.

Throws:

  Exceptions caused by memory allocation.

See also:

  `std::allocator_arg_t`

###### Move constructor

    promise( promise && other) noexcept;

Effects:

  Creates a promise by moving the shared state from `other`.

Postcondition:

  `other` contains no valid shared state.

Throws:

  Nothing.

###### Destructor

    ~promise();

Effects:

  Destroys `*this` and abandons the shared state if shared state is ready; otherwise stores `future_error` with error condition `future_errc::broken_promise` as if by `promise::set_exception()`: the shared state is set ready.

##### Member function `operator=`()

    promise & operator=( promise && other) noexcept;

Effects:

  Transfers the ownership of shared state to `*this`.

Postcondition:

  `other` contains no valid shared state.

Throws:

  Nothing.

##### Member function `swap`()

    void swap( promise & other) noexcept;

Effects:

  Swaps the shared state between other and `*this`.

Throws:

  Nothing.

##### Member function `get_future`()

    future< R > get_future();

Returns:

  A `future<>` with the same shared state.

Throws:

  `future_error` with `future_errc::future_already_retrieved` or `future_errc::no_state`.

##### Member function `set_value`()

    void set_value( R const& value);  // member only of generic promise template
    void set_value( R && value);      // member only of generic promise template
    void set_value( R & value);       // member only of promise< R & > template
    void set_value();                 // member only of promise< void > template

Effects:

  Store the result in the shared state and marks the state as ready.

Throws:

  `future_error` with `future_errc::future_already_satisfied` or `future_errc::no_state`.

##### Member function `set_exception`()

    void set_exception( std::exception_ptr);

Effects:

  Store an exception pointer in the shared state and marks the state as ready.

Throws:

  `future_error` with `future_errc::future_already_satisfied` or `future_errc::no_state`.

##### Non-member function `swap()`

    template< typename R >
    void swap( promise< R > & l, promise< R > & r) noexcept;

Effects:

  Same as `l.swap( r)`.