]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
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 | |
6 | ] | |
7 | ||
8 | [#class_promise] | |
9 | [section:promise Template `promise<>`] | |
10 | ||
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]. | |
14 | ||
15 | #include <boost/fiber/future/promise.hpp> | |
16 | ||
17 | namespace boost { | |
18 | namespace fibers { | |
19 | ||
20 | template< typename R > | |
21 | class promise { | |
22 | public: | |
23 | promise(); | |
24 | ||
25 | template< typename __Allocator__ > | |
26 | promise( __allocator_arg_t__, Allocator); | |
27 | ||
28 | promise( promise &&) noexcept; | |
29 | ||
30 | promise & operator=( promise &&) noexcept; | |
31 | ||
32 | promise( promise const&) = delete; | |
33 | ||
34 | promise & operator=( promise const&) = delete; | |
35 | ||
36 | ~promise(); | |
37 | ||
38 | void swap( promise &) noexcept; | |
39 | ||
40 | future< R > get_future(); | |
41 | ||
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 | |
46 | ||
47 | void set_exception( std::exception_ptr p); | |
48 | }; | |
49 | ||
50 | template< typename R > | |
51 | void swap( promise< R > &, promise< R > &) noexcept; | |
52 | ||
53 | } | |
54 | ||
55 | [heading Default constructor] | |
56 | ||
57 | promise(); | |
58 | ||
59 | [variablelist | |
60 | [[Effects:] [Creates a promise with an empty [link shared_state shared state].]] | |
61 | [[Throws:] [Exceptions caused by memory allocation.]] | |
62 | ] | |
63 | ||
64 | [heading Constructor] | |
65 | ||
66 | template< typename __Allocator__ > | |
67 | promise( __allocator_arg_t__, Allocator alloc); | |
68 | ||
69 | [variablelist | |
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__]] | |
73 | ] | |
74 | ||
75 | [heading Move constructor] | |
76 | ||
77 | promise( promise && other) noexcept; | |
78 | ||
79 | [variablelist | |
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.]] | |
83 | ] | |
84 | ||
85 | [heading Destructor] | |
86 | ||
87 | ~promise(); | |
88 | ||
89 | [variablelist | |
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.]] | |
94 | ] | |
95 | ||
96 | [operator_heading promise..operator_assign..operator=] | |
97 | ||
98 | promise & operator=( promise && other) noexcept; | |
99 | ||
100 | [variablelist | |
101 | [[Effects:] [Transfers the ownership of [link shared_state shared state] to `*this`.]] | |
102 | [[Postcondition:] [`other` contains no valid shared state.]] | |
103 | [[Throws:] [Nothing.]] | |
104 | ] | |
105 | ||
106 | [member_heading promise..swap] | |
107 | ||
108 | void swap( promise & other) noexcept; | |
109 | ||
110 | [variablelist | |
111 | [[Effects:] [Swaps the [link shared_state shared state] between other and `*this`.]] | |
112 | [[Throws:] [Nothing.]] | |
113 | ] | |
114 | ||
115 | [member_heading promise..get_future] | |
116 | ||
117 | future< R > get_future(); | |
118 | ||
119 | [variablelist | |
120 | [[Returns:] [A __future__ with the same [link shared_state shared state].]] | |
121 | [[Throws:] [__future_error__ with __already_retrieved__ or __no_state__.]] | |
122 | ] | |
123 | ||
124 | [member_heading promise..set_value] | |
125 | ||
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 | |
130 | ||
131 | [variablelist | |
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__.]] | |
134 | ] | |
135 | ||
136 | [member_heading promise..set_exception] | |
137 | ||
138 | void set_exception( std::exception_ptr); | |
139 | ||
140 | [variablelist | |
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__.]] | |
143 | ] | |
144 | ||
145 | [function_heading_for swap..promise] | |
146 | ||
147 | template< typename R > | |
148 | void swap( promise< R > & l, promise< R > & r) noexcept; | |
149 | ||
150 | [variablelist | |
151 | [[Effects:] [Same as `l.swap( r)`.]] | |
152 | ] | |
153 | ||
154 | [endsect] |