ceph/src/boost/libs/fiber/doc/promise.qbk

   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]