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 11A __promise__ provides a mechanism to store a value (or exception) that can 12later 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 91state] if shared state is ready; otherwise stores __future_error__ with error 92condition __broken_promise__ as if by [member_link promise..set_exception]: 93the 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] 155