ceph/src/boost/libs/fiber/doc/packaged_task.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_packaged_task]
   9 [section:packaged_task Template `packaged_task<>`]
  10
  11 A __packaged_task__ wraps a callable target that returns a value so that the
  12 return value can be computed asynchronously.
  13
  14 Conventional usage of `packaged_task<>` is like this:
  15
  16 # Instantiate `packaged_task<>` with template arguments matching the signature
  17   of the callable. Pass the callable to the [link packaged_task_packaged_task
  18   constructor].
  19 # Call [member_link packaged_task..get_future] and capture the returned
  20   [template_link future] instance.
  21 # Launch a [class_link fiber] to run the new `packaged_task<>`, passing any
  22   arguments required by the original callable.
  23 # Call [member_link fiber..detach] on the newly-launched `fiber`.
  24 # At some later point, retrieve the result from the `future<>`.
  25
  26 This is, in fact, pretty much what [ns_function_link fibers..async]
  27 encapsulates.
  28
  29         #include <boost/fiber/future/packaged_task.hpp>
  30
  31         namespace boost {
  32         namespace fibers {
  33
  34         template< class R, typename ... Args >
  35         class packaged_task< R( Args ... ) > {
  36         public:
  37             packaged_task() noexcept;
  38
  39             template< typename Fn >
  40             explicit packaged_task( Fn &&);
  41
  42             template< typename Fn, typename __Allocator__ >
  43             packaged_task( __allocator_arg_t__, Allocator const&, Fn &&);
  44
  45             packaged_task( packaged_task &&) noexcept;
  46
  47             packaged_task & operator=( packaged_task &&) noexcept;
  48
  49             packaged_task( packaged_task const&) = delete;
  50
  51             packaged_task & operator=( packaged_task const&) = delete;
  52
  53             ~packaged_task();
  54
  55             void swap( packaged_task &) noexcept;
  56
  57             bool valid() const noexcept;
  58
  59             future< R > get_future();
  60
  61             void operator()( Args ...);
  62
  63             void reset();
  64         };
  65
  66         template< typename Signature >
  67         void swap( packaged_task< Signature > &, packaged_task< Signature > &) noexcept;
  68
  69         }}
  70
  71 [heading Default constructor `packaged_task()`]
  72
  73         packaged_task() noexcept;
  74
  75 [variablelist
  76 [[Effects:] [Constructs an object of class `packaged_task` with no [link
  77 shared_state shared state].]]
  78 [[Throws:] [Nothing.]]
  79 ]
  80
  81 [#packaged_task_packaged_task]
  82 [heading Templated constructor `packaged_task()`]
  83
  84         template< typename Fn >
  85         explicit packaged_task( Fn && fn);
  86
  87         template< typename Fn, typename __Allocator__ >
  88         packaged_task( __allocator_arg_t__, Allocator const& alloc, Fn && fn);
  89
  90 [variablelist
  91 [[Effects:] [Constructs an object of class `packaged_task` with a [link
  92 shared_state shared state] and copies or moves the callable target `fn` to
  93 internal storage.]]
  94 [[Throws:] [Exceptions caused by memory allocation.]]
  95 [[Note:] [The signature of `Fn` should have a return type convertible to `R`.]]
  96 [[See also:] [__allocator_arg_t__]]
  97 ]
  98
  99 [heading Move constructor]
 100
 101         packaged_task( packaged_task && other) noexcept;
 102
 103 [variablelist
 104 [[Effects:] [Creates a packaged_task by moving the [link shared_state shared
 105 state] from `other`.]]
 106 [[Postcondition:] [`other` contains no valid shared state.]]
 107 [[Throws:] [Nothing.]]
 108 ]
 109
 110 [heading Destructor]
 111
 112         ~packaged_task();
 113
 114 [variablelist
 115 [[Effects:] [Destroys `*this` and abandons the [link shared_state shared
 116 state] if shared state is ready; otherwise stores __future_error__ with error
 117 condition __broken_promise__ as if by [member_link promise..set_exception]:
 118 the shared state is set ready.]]
 119 ]
 120
 121 [operator_heading packaged_task..operator_assign..operator=]
 122
 123         packaged_task & operator=( packaged_task && other) noexcept;
 124
 125 [variablelist
 126 [[Effects:] [Transfers the ownership of [link shared_state shared state] to
 127 `*this`.]]
 128 [[Postcondition:] [`other` contains no valid shared state.]]
 129 [[Throws:] [Nothing.]]
 130 ]
 131
 132 [member_heading packaged_task..swap]
 133
 134         void swap( packaged_task & other) noexcept;
 135
 136 [variablelist
 137 [[Effects:] [Swaps the [link shared_state shared state] between other and
 138 `*this`.]]
 139 [[Throws:] [Nothing.]]
 140 ]
 141
 142 [member_heading packaged_task..valid]
 143
 144         bool valid() const noexcept;
 145
 146 [variablelist
 147 [[Effects:] [Returns `true` if `*this` contains a [link shared_state shared
 148 state].]]
 149 [[Throws:] [Nothing.]]
 150 ]
 151
 152 [member_heading packaged_task..get_future]
 153
 154         future< R > get_future();
 155
 156 [variablelist
 157 [[Returns:] [A __future__ with the same [link shared_state shared state].]]
 158 [[Throws:] [__future_error__ with __already_retrieved__ or __no_state__.]]
 159 ]
 160
 161 [operator_heading packaged_task..operator_apply..operator()]
 162
 163         void operator()( Args && ... args);
 164
 165 [variablelist
 166 [[Effects:] [Invokes the stored callable target. Any exception thrown by the
 167 callable target `fn` is stored in the [link shared_state shared state] as if
 168 by [member_link promise..set_exception]. Otherwise, the value returned by `fn`
 169 is stored in the shared state as if by [member_link promise..set_value].]]
 170 [[Throws:] [__future_error__ with __no_state__.]]
 171 ]
 172
 173 [member_heading packaged_task..reset]
 174
 175         void reset();
 176
 177 [variablelist
 178 [[Effects:] [Resets the [link shared_state shared state] and abandons the
 179 result of previous executions. A new shared state is constructed.]]
 180 [[Throws:] [__future_error__ with __no_state__.]]
 181 ]
 182
 183 [function_heading_for swap..packaged_task]
 184
 185     template< typename Signature >
 186     void swap( packaged_task< Signature > & l, packaged_task< Signature > & r) noexcept;
 187
 188 [variablelist
 189 [[Effects:] [Same as `l.swap( r)`.]]
 190 ]
 191
 192 [endsect]