2 Copyright Oliver Kowalke 2013.
3 Distributed under the Boost Software License, Version 1.0.
4 (See accompanying file LICENSE_1_0.txt or copy at
5 http://www.boost.org/LICENSE_1_0.txt
9 [section:promise Template `promise<>`]
11 A __promise__ provides a mechanism to store a value (or exception) that can
12 later be retrieved from the corresponding __future__ object. `promise<>` and
13 `future<>` communicate via their underlying [link shared_state shared state].
15 #include <boost/fiber/future/promise.hpp>
20 template< typename R >
25 template< typename __Allocator__ >
26 promise( __allocator_arg_t__, Allocator);
28 promise( promise &&) noexcept;
30 promise & operator=( promise &&) noexcept;
32 promise( promise const&) = delete;
34 promise & operator=( promise const&) = delete;
38 void swap( promise &) noexcept;
40 future< R > get_future();
42 void set_value( R const&); // member only of generic promise template
43 void set_value( R &&); // member only of generic promise template
44 void set_value( R &); // member only of promise< R & > template
45 void set_value(); // member only of promise< void > template
47 void set_exception( std::exception_ptr p);
50 template< typename R >
51 void swap( promise< R > &, promise< R > &) noexcept;
55 [heading Default constructor]
60 [[Effects:] [Creates a promise with an empty [link shared_state shared state].]]
61 [[Throws:] [Exceptions caused by memory allocation.]]
66 template< typename __Allocator__ >
67 promise( __allocator_arg_t__, Allocator alloc);
70 [[Effects:] [Creates a promise with an empty [link shared_state shared state] by using `alloc`.]]
71 [[Throws:] [Exceptions caused by memory allocation.]]
72 [[See also:] [__allocator_arg_t__]]
75 [heading Move constructor]
77 promise( promise && other) noexcept;
80 [[Effects:] [Creates a promise by moving the [link shared_state shared state] from `other`.]]
81 [[Postcondition:] [`other` contains no valid shared state.]]
82 [[Throws:] [Nothing.]]
90 [[Effects:] [Destroys `*this` and abandons the [link shared_state shared
91 state] if shared state is ready; otherwise stores __future_error__ with error
92 condition __broken_promise__ as if by [member_link promise..set_exception]:
93 the shared state is set ready.]]
96 [operator_heading promise..operator_assign..operator=]
98 promise & operator=( promise && other) noexcept;
101 [[Effects:] [Transfers the ownership of [link shared_state shared state] to `*this`.]]
102 [[Postcondition:] [`other` contains no valid shared state.]]
103 [[Throws:] [Nothing.]]
106 [member_heading promise..swap]
108 void swap( promise & other) noexcept;
111 [[Effects:] [Swaps the [link shared_state shared state] between other and `*this`.]]
112 [[Throws:] [Nothing.]]
115 [member_heading promise..get_future]
117 future< R > get_future();
120 [[Returns:] [A __future__ with the same [link shared_state shared state].]]
121 [[Throws:] [__future_error__ with __already_retrieved__ or __no_state__.]]
124 [member_heading promise..set_value]
126 void set_value( R const& value); // member only of generic promise template
127 void set_value( R && value); // member only of generic promise template
128 void set_value( R & value); // member only of promise< R & > template
129 void set_value(); // member only of promise< void > template
132 [[Effects:] [Store the result in the [link shared_state shared state] and marks the state as ready.]]
133 [[Throws:] [__future_error__ with __already_satisfied__ or __no_state__.]]
136 [member_heading promise..set_exception]
138 void set_exception( std::exception_ptr);
141 [[Effects:] [Store an exception pointer in the [link shared_state shared state] and marks the state as ready.]]
142 [[Throws:] [__future_error__ with __already_satisfied__ or __no_state__.]]
145 [function_heading_for swap..promise]
147 template< typename R >
148 void swap( promise< R > & l, promise< R > & r) noexcept;
151 [[Effects:] [Same as `l.swap( r)`.]]