ceph/src/boost/libs/fiber/doc/fibers.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 [library Fiber
   9     [quickbook 1.5]
  10     [authors [Kowalke, Oliver]]
  11     [copyright 2013 Oliver Kowalke]
  12     [id fiber]
  13     [purpose C++ Library to cooperatively schedule and synchronize micro-threads]
  14     [category text]
  15     [license
  16         Distributed under the Boost Software License, Version 1.0.
  17         (See accompanying file LICENSE_1_0.txt or copy at
  18         [@http://www.boost.org/LICENSE_1_0.txt])
  19     ]
  20 ]
  21
  22
  23 [def __boost_asio__ [@http://www.boost.org/doc/libs/release/libs/asio/index.html Boost.Asio]]
  24 [def __boost_context__ [@http://www.boost.org/doc/libs/release/libs/context/index.html Boost.Context]]
  25 [def __boost_fiber__ [*Boost.Fiber]]
  26 [def __boost_intrusive__ [@http://www.boost.org/doc/libs/release/libs/intrusive/index.html Boost.Intrusive]]
  27 [def __boost_thread__ [@http://www.boost.org/doc/libs/release/libs/thread/index.html Boost.Thread]]
  28 [def __std_thread__ [@http://en.cppreference.com/w/cpp/thread standard thread support library]]
  29
  30 [def __async_result__ ['async-result]]
  31 [def __blocked__ [link blocking ['blocked]]]
  32 [def __lockable_concept__ ['lockable concept]]
  33 [def __not_a_fiber__ ['not-a-fiber]]
  34 [def __rendezvous__ ['rendezvous]]
  35
  36 [/ important especially for [,] to avoid a space between empty argument
  37    brackets and expansion: the space, if any, becomes part of the expansion!]
  38 [template mdash[]'''&mdash;''']
  39 [template ,[]'''&#8217;''']
  40 [template "[text]'''&#8220;'''[text]'''&#8221;''']
  41 [template superscript[exp]'''<superscript>'''[exp]'''</superscript>''']
  42 [/ "isn[t]" is slightly more readable than "isn[,]t", and so forth]
  43 [template s[][,]s]
  44 [template t[][,]t]
  45
  46 [template class_heading[class_name]
  47 [hding class_[class_name]..Class [`[class_name]]]
  48 ]
  49 [template class_link[class_name][dblink class_[class_name]..[`[class_name]]]]
  50
  51 [template template_heading[class_name]
  52 [hding class_[class_name]..Template [`[class_name]<>]]
  53 ]
  54 [template template_link[class_name][dblink class_[class_name]..[`[class_name]<>]]]
  55
  56 [template member_heading[class_name method_name]
  57 [operator_heading [class_name]..[method_name]..[method_name]]
  58 ]
  59 [template member_link[class_name method_name][operator_link [class_name]..[method_name]..[method_name]]]
  60
  61 [template operator_heading[class_name method_name method_text]
  62 [hding [class_name]_[method_name]..Member function [`[method_text]]()]
  63 ]
  64 [template operator_link[class_name method_name method_text][dblink [class_name]_[method_name]..[`[class_name]::[method_text]()]]]
  65
  66 [template template_member_heading[class_name method_name]
  67 [hding [class_name]_[method_name]..Templated member function [`[method_name]]()]
  68 ]
  69 [template template_member_link[class_name method_name][member_link [class_name]..[method_name]]]
  70
  71 [template static_member_heading[class_name method_name]
  72 [hding [class_name]_[method_name]..Static member function [`[method_name]]()]
  73 ]
  74 [template static_member_link[class_name method_name][member_link [class_name]..[method_name]]]
  75
  76 [template data_member_heading[class_name member_name]
  77 [hding [class_name]_[member_name]..Data member [`[member_name]]]
  78 ]
  79 [template data_member_link[class_name member_name][dblink [class_name]_[member_name]..[`[class_name]::[member_name]]]]
  80
  81 [template function_heading[function_name]
  82 [hding [function_name]..Non-member function [`[function_name]()]]
  83 ]
  84 [template function_link[function_name][dblink [function_name]..[`[function_name]()]]]
  85
  86 [template function_heading_for[function_name arg]
  87 [hding [function_name]\_for\_[arg]..Non-member function [`[function_name]()]]
  88 ]
  89 [template function_link_for[function_name arg][dblink [function_name]\_for\_[arg]..[`[function_name]()]]]
  90
  91 [template ns_function_heading[namespace function_name]
  92 [hding [namespace]_[function_name]..Non-member function [`[namespace]::[function_name]()]]
  93 ]
  94 [template ns_function_link[namespace function_name][dblink [namespace]_[function_name]..[`[namespace]::[function_name]()]]]
  95
  96 [template anchor[name]'''<anchor id="'''[name]'''"/>''']
  97 [template hding[name title]
  98 '''<bridgehead renderas="sect4" id="'''[name]_bridgehead'''">
  99   <phrase id="'''[name]'''"/>
 100   <link linkend="'''[name]'''">'''[title]'''</link>
 101 </bridgehead>'''
 102 ]
 103 [template dblink[id text]'''<link linkend="'''[id]'''">'''[text]'''</link>''']
 104 [template `[text]'''<code>'''[text]'''</code>''']
 105
 106 [def __allocator_arg_t__ [@http://en.cppreference.com/w/cpp/memory/allocator_arg_t `std::allocator_arg_t`]]
 107 [def __Allocator__ [@http://en.cppreference.com/w/cpp/concept/Allocator `Allocator`]]
 108 [def __allocator__ [@http://en.cppreference.com/w/cpp/memory/allocator `std::allocator< T >`]]
 109 [def __barrier__ [class_link barrier]]
 110 [def __condition__ [class_link condition_variable]]
 111 [def __econtext__ [@http://www.boost.org/doc/libs/release/libs/context/doc/html/context/ecv2.html ['execution_context]]]
 112 [def __fiber__ [class_link fiber]]
 113 [def __fiber_error__ `fiber_error`]
 114 [def __fiber_group__ [class_link fiber_group]]
 115 [def __fiber_error__ `fiber_error`]
 116 [def __fibers__ `fibers`]
 117 [def __fixedsize_stack__ [class_link fixedsize_stack]]
 118 [def __future_error__ `future_error`]
 119 [def __future__ [template_link future]]
 120 [def __joinable__ [member_link fiber..joinable]]
 121 [def __lock_error__ `lock_error`]
 122 [def __mutex__ [class_link mutex]]
 123 [def __ofixedsize_stack__ [class_link pooled_fixedsize_stack]]
 124 [def __packaged_task__ [template_link packaged_task]]
 125 [def __pfixedsize_stack__ [class_link protected_fixedsize_stack]]
 126 [def __promise__ [template_link promise]]
 127 [def __recursive_mutex__ [class_link recursive_mutex]]
 128 [def __recursive_timed_mutex__ [class_link recursive_timed_mutex]]
 129 [def __segmented_stack__ [class_link segmented_stack]]
 130 [def __segmented_stack_stack__ ['segmented_stack-stack]]
 131 [def __shared_future__ [template_link shared_future]]
 132 [def __stack_allocator__ ['stack_allocator]]
 133 [def __stack_allocator_concept__ [link stack_allocator_concept ['stack-allocator concept]]]
 134 [def __StackAllocator__ [link stack_allocator_concept `StackAllocator`]]
 135 [def __stack_context__ [@http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack/stack_context.html `stack_context`]]
 136 [def __timed_mutex__ [class_link timed_mutex]]
 137 [def __unique_lock__ [@http://en.cppreference.com/w/cpp/thread/unique_lock `std::unique_lock`]]
 138 [def __wait_for__ [member_link future..wait_for]]
 139 [def __wait__ [member_link future..wait]]
 140 [def __wait_until__ [member_link future..wait_until]]
 141
 142 [def __no_state__ `future_errc::no_state`]
 143 [def __broken_promise__ `future_errc::broken_promise`]
 144 [def __already_retrieved__ `future_errc::future_already_retrieved`]
 145 [def __already_satisfied__ `future_errc::future_already_satisfied`]
 146
 147 [def __algo__ [class_link algorithm]]
 148 [def __algo_awakened__ [member_link algorithm..awakened]]
 149 [def __algo_pick_next__ [member_link algorithm..pick_next]]
 150 [def __async__ `async()`]
 151 [def __barrier_wait__ [member_link barrier..wait]]
 152 [def __cond_wait_for__ [member_link condition_variable..wait_for]]
 153 [def __cond_wait__ [member_link condition_variable..wait]]
 154 [def __cond_wait_until__ [member_link condition_variable..wait_until]]
 155 [def __cond_any_wait_for__ [member_link condition_variable_any..wait_for]]
 156 [def __cond_any_wait__ [member_link condition_variable_any..wait]]
 157 [def __cond_any_wait_until__ [member_link condition_variable_any..wait_until]]
 158 [def __context_attach__ [member_link context..attach]]
 159 [def __context_detach__ [member_link context..detach]]
 160 [def __detach__ [member_link fiber..detach]]
 161 [def __fiber_id__ [dblink class_fiber_id..`fiber::id`]]
 162 [def __fsp__ [class_link fiber_specific_ptr]]
 163 [def __future_get__ [member_link future..get]]
 164 [def __get_id__ [member_link fiber..get_id]]
 165 [def __io_service__ [@http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service.html `boost::asio::io_service`]]
 166 [def __join__ [member_link fiber..join]]
 167 [def __mutex_lock__ [member_link mutex..lock]]
 168 [def __mutex_try_lock__ [member_link mutex..try_lock]]
 169 [def __run_service__ `boost::fibers::asio::run_svc()`]
 170 [def __shared_future_get__ [member_link shared_future..get]]
 171 [def __sleep_for__ [ns_function_link this_fiber..sleep_for]]
 172 [def __sleep_until__ [ns_function_link this_fiber..sleep_until]]
 173 [def __yield_context__ ['boost::asio::yield_context]]
 174 [def __yield_fiber__ ['boost::fibers::asio::yield_context]]
 175 [def __yield__ [ns_function_link this_fiber..yield]]
 176
 177 [def __lock__ `lock()`]
 178 [def __try_lock_for__ `try_lock_for()`]
 179 [def __try_lock__ `try_lock()`]
 180 [def __try_lock_until__ `try_lock_until()`]
 181 [def __unlock__ `unlock()`]
 182
 183
 184 [include overview.qbk]
 185 [include fiber.qbk]
 186 [include scheduling.qbk]
 187 [include stack.qbk]
 188 [#synchronization]
 189 [section:synchronization Synchronization]
 190
 191 In general, __boost_fiber__ synchronization objects can neither be moved nor
 192 copied. A synchronization object acts as a mutually-agreed rendezvous point
 193 between different fibers. If such an object were copied somewhere else, the
 194 new copy would have no consumers. If such an object were ['moved] somewhere
 195 else, leaving the original instance in an unspecified state, existing
 196 consumers would behave strangely.
 197
 198 The fiber synchronization objects provided by this library will, by default,
 199 safely synchronize fibers running on different threads. However, this level of
 200 synchronization can be removed (for performance) by building the library with
 201 [*`BOOST_FIBERS_NO_ATOMICS`] defined. When the library is built with that macro,
 202 you must ensure that all the fibers referencing a particular synchronization
 203 object are running in the same thread.
 204
 205 [include mutexes.qbk]
 206 [include condition_variables.qbk]
 207 [include barrier.qbk]
 208 [include channel.qbk]
 209 [include futures.qbk]
 210 [endsect]
 211 [include fls.qbk]
 212 [/[include asio.qbk]]
 213 [include migration.qbk]
 214 [include callbacks.qbk]
 215 [include nonblocking.qbk]
 216 [include when_any.qbk]
 217 [include integration.qbk]
 218 [include performance.qbk]
 219 [include customization.qbk]
 220 [include rationale.qbk]
 221 [include acknowledgements.qbk]
 222 [include installing.qbk]