304 lines
12 KiB
Plaintext
304 lines
12 KiB
Plaintext
[/
|
|
Copyright Oliver Kowalke 2013.
|
|
Distributed under the Boost Software License, Version 1.0.
|
|
(See accompanying file LICENSE_1_0.txt or copy at
|
|
http://www.boost.org/LICENSE_1_0.txt
|
|
]
|
|
|
|
[library Fiber
|
|
[quickbook 1.5]
|
|
[authors [Kowalke, Oliver]]
|
|
[copyright 2013 Oliver Kowalke]
|
|
[id fiber]
|
|
[purpose C++ Library to cooperatively schedule and synchronize micro-threads]
|
|
[category text]
|
|
[license
|
|
Distributed under the Boost Software License, Version 1.0.
|
|
(See accompanying file LICENSE_1_0.txt or copy at
|
|
[@http://www.boost.org/LICENSE_1_0.txt])
|
|
]
|
|
]
|
|
|
|
[/ important especially for [,] to avoid a space between empty argument
|
|
brackets and expansion: the space, if any, becomes part of the expansion!]
|
|
[template mdash[]'''—''']
|
|
[template ,[]'''’''']
|
|
[template "[text]'''“'''[text]'''”''']
|
|
[template superscript[exp]'''<superscript>'''[exp]'''</superscript>''']
|
|
[/ "isn[t]" is slightly more readable than "isn[,]t", and so forth]
|
|
[template s[][,]s]
|
|
[template t[][,]t]
|
|
|
|
[template class_heading[class_name]
|
|
[hding class_[class_name]..Class [`[class_name]]]
|
|
]
|
|
[template class_link[class_name][dblink class_[class_name]..[`[class_name]]]]
|
|
|
|
[template template_heading[class_name]
|
|
[hding class_[class_name]..Template [`[class_name]<>]]
|
|
]
|
|
[template template_link[class_name][dblink class_[class_name]..[`[class_name]<>]]]
|
|
|
|
[template member_heading[class_name method_name]
|
|
[operator_heading [class_name]..[method_name]..[method_name]]
|
|
]
|
|
[template member_link[class_name method_name][operator_link [class_name]..[method_name]..[method_name]]]
|
|
|
|
[template operator_heading[class_name method_name method_text]
|
|
[hding [class_name]_[method_name]..Member function [`[method_text]]()]
|
|
]
|
|
[template operator_link[class_name method_name method_text][dblink [class_name]_[method_name]..[`[class_name]::[method_text]()]]]
|
|
|
|
[template template_member_heading[class_name method_name]
|
|
[hding [class_name]_[method_name]..Templated member function [`[method_name]]()]
|
|
]
|
|
[template template_member_link[class_name method_name][member_link [class_name]..[method_name]]]
|
|
|
|
[template static_member_heading[class_name method_name]
|
|
[hding [class_name]_[method_name]..Static member function [`[method_name]]()]
|
|
]
|
|
[template static_member_link[class_name method_name][member_link [class_name]..[method_name]]]
|
|
|
|
[template data_member_heading[class_name member_name]
|
|
[hding [class_name]_[member_name]..Data member [`[member_name]]]
|
|
]
|
|
[template data_member_link[class_name member_name][dblink [class_name]_[member_name]..[`[class_name]::[member_name]]]]
|
|
|
|
[template function_heading[function_name]
|
|
[hding [function_name]..Non-member function [`[function_name]()]]
|
|
]
|
|
[template function_link[function_name][dblink [function_name]..[`[function_name]()]]]
|
|
|
|
[template function_heading_for[function_name arg]
|
|
[hding [function_name]\_for\_[arg]..Non-member function [`[function_name]()]]
|
|
]
|
|
[template function_link_for[function_name arg][dblink [function_name]\_for\_[arg]..[`[function_name]()]]]
|
|
|
|
[template ns_class_heading[namespace class_name]
|
|
[hding class_[namespace]_[class_name]..Class [`[namespace]::[class_name]]]
|
|
]
|
|
[template ns_class_link[namespace class_name][dblink class_[namespace]_[class_name]..[`[namespace]::[class_name]]]]
|
|
|
|
[template ns_member_heading[namespace class_name method_name]
|
|
[ns_operator_heading [namespace]..[class_name]..[method_name]..[method_name]]
|
|
]
|
|
[template ns_member_link[namespace class_name method_name][ns_operator_link [namespace]..[class_name]..[method_name]..[method_name]]]
|
|
|
|
[template ns_operator_heading[namespace class_name method_name method_text]
|
|
[hding [namespace]_[class_name]_[method_name]..Member function [`[method_text]]()]
|
|
]
|
|
[template ns_operator_link[namespace class_name method_name method_text][dblink [namespace]_[class_name]_[method_name]..[`[namespace]::[class_name]::[method_text]()]]]
|
|
|
|
[template ns_data_member_heading[namespace class_name member_name]
|
|
[hding [namespace]_[class_name]_[member_name]..Data member [`[member_name]]]
|
|
]
|
|
[template ns_data_member_link[namespace class_name member_name][dblink [namespace]_[class_name]_[member_name]..[`[namespace]::[class_name]::[member_name]]]]
|
|
|
|
[template ns_function_heading[namespace function_name]
|
|
[hding [namespace]_[function_name]..Non-member function [`[namespace]::[function_name]()]]
|
|
]
|
|
[template ns_function_link[namespace function_name][dblink [namespace]_[function_name]..[`[namespace]::[function_name]()]]]
|
|
|
|
[template anchor[name]'''<anchor id="'''[name]'''"/>''']
|
|
[template hding[name title]
|
|
'''<bridgehead renderas="sect4" id="'''[name]_bridgehead'''">
|
|
<phrase id="'''[name]'''"/>
|
|
<link linkend="'''[name]'''">'''[title]'''</link>
|
|
</bridgehead>'''
|
|
]
|
|
[template dblink[id text]'''<link linkend="'''[id]'''">'''[text]'''</link>''']
|
|
[template `[text]'''<code>'''[text]'''</code>''']
|
|
|
|
|
|
[def __boost_asio__ [@http://www.boost.org/doc/libs/release/libs/asio/index.html Boost.Asio]]
|
|
[def __boost_context__ [@http://www.boost.org/doc/libs/release/libs/context/index.html Boost.Context]]
|
|
[def __boost_fiber__ [*Boost.Fiber]]
|
|
[def __boost_intrusive__ [@http://www.boost.org/doc/libs/release/libs/intrusive/index.html Boost.Intrusive]]
|
|
[def __boost_thread__ [@http://www.boost.org/doc/libs/release/libs/thread/index.html Boost.Thread]]
|
|
[def __std_thread__ [@http://en.cppreference.com/w/cpp/thread standard thread support library]]
|
|
|
|
[def __async_result__ ['async-result]]
|
|
[def __blocked__ [link blocking ['blocked]]]
|
|
[def __lockable_concept__ ['lockable concept]]
|
|
[def __not_a_fiber__ ['not-a-fiber]]
|
|
[def __rendezvous__ ['rendezvous]]
|
|
|
|
[def __allocator_arg_t__ [@http://en.cppreference.com/w/cpp/memory/allocator_arg_t `std::allocator_arg_t`]]
|
|
[def __Allocator__ [@http://en.cppreference.com/w/cpp/concept/Allocator `Allocator`]]
|
|
[def __allocator__ [@http://en.cppreference.com/w/cpp/memory/allocator `std::allocator< T >`]]
|
|
[def __barrier__ [class_link barrier]]
|
|
[def __cc__ [@http://www.boost.org/doc/libs/release/libs/context/doc/html/context/cc.html ['call/cc]]]
|
|
[def __condition__ [class_link condition_variable]]
|
|
[def __fcontext__ `fcontext_t`]
|
|
[def __fiber__ [class_link fiber]]
|
|
[def __fiber_error__ `fiber_error`]
|
|
[def __fiber_error__ `fiber_error`]
|
|
[def __fiber_group__ [class_link fiber_group]]
|
|
[def __fibers__ `fibers`]
|
|
[def __fixedsize_stack__ [class_link fixedsize_stack]]
|
|
[def __future_error__ `future_error`]
|
|
[def __future__ [template_link future]]
|
|
[def __joinable__ [member_link fiber..joinable]]
|
|
[def __lock_error__ `lock_error`]
|
|
[def __mutex__ [class_link mutex]]
|
|
[def __numa_work_stealing__ [ns_class_link numa..work_stealing]]
|
|
[def __ofixedsize_stack__ [class_link pooled_fixedsize_stack]]
|
|
[def __packaged_task__ [template_link packaged_task]]
|
|
[def __pfixedsize_stack__ [class_link protected_fixedsize_stack]]
|
|
[def __promise__ [template_link promise]]
|
|
[def __recursive_mutex__ [class_link recursive_mutex]]
|
|
[def __recursive_timed_mutex__ [class_link recursive_timed_mutex]]
|
|
[def __round_robin__ [class_link round_robin]]
|
|
[def __segmented_stack__ [class_link segmented_stack]]
|
|
[def __segmented_stack_stack__ ['segmented_stack-stack]]
|
|
[def __shared_future__ [template_link shared_future]]
|
|
[def __shared_work__ [class_link shared_work]]
|
|
[def __stack_allocator_concept__ [link stack_allocator_concept ['stack-allocator concept]]]
|
|
[def __StackAllocator__ [link stack_allocator_concept `StackAllocator`]]
|
|
[def __stack_allocator__ ['stack_allocator]]
|
|
[def __stack_context__ [@http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack/stack_context.html `stack_context`]]
|
|
[def __timed_mutex__ [class_link timed_mutex]]
|
|
[def __ucontext__ `ucontext_t`]
|
|
[def __unique_lock__ [@http://en.cppreference.com/w/cpp/thread/unique_lock `std::unique_lock`]]
|
|
[def __wait_for__ [member_link future..wait_for]]
|
|
[def __wait__ [member_link future..wait]]
|
|
[def __wait_until__ [member_link future..wait_until]]
|
|
[def __winfib__ `WinFiber`]
|
|
[def __work_stealing__ [class_link work_stealing]]
|
|
|
|
[def __no_state__ `future_errc::no_state`]
|
|
[def __broken_promise__ `future_errc::broken_promise`]
|
|
[def __already_retrieved__ `future_errc::future_already_retrieved`]
|
|
[def __already_satisfied__ `future_errc::future_already_satisfied`]
|
|
|
|
[def __algo__ [class_link algorithm]]
|
|
[def __algo_awakened__ [member_link algorithm..awakened]]
|
|
[def __algo_pick_next__ [member_link algorithm..pick_next]]
|
|
[def __async__ `async()`]
|
|
[def __barrier_wait__ [member_link barrier..wait]]
|
|
[def __cond_wait_for__ [member_link condition_variable..wait_for]]
|
|
[def __cond_wait__ [member_link condition_variable..wait]]
|
|
[def __cond_wait_until__ [member_link condition_variable..wait_until]]
|
|
[def __cond_any_wait_for__ [member_link condition_variable_any..wait_for]]
|
|
[def __cond_any_wait__ [member_link condition_variable_any..wait]]
|
|
[def __cond_any_wait_until__ [member_link condition_variable_any..wait_until]]
|
|
[def __context_attach__ [member_link context..attach]]
|
|
[def __context_detach__ [member_link context..detach]]
|
|
[def __detach__ [member_link fiber..detach]]
|
|
[def __fiber_id__ [dblink class_fiber_id..`fiber::id`]]
|
|
[def __fsp__ [class_link fiber_specific_ptr]]
|
|
[def __future_get__ [member_link future..get]]
|
|
[def __get_id__ [member_link fiber..get_id]]
|
|
[def __io_service__ [@http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service.html `boost::asio::io_service`]]
|
|
[def __join__ [member_link fiber..join]]
|
|
[def __mutex_lock__ [member_link mutex..lock]]
|
|
[def __mutex_try_lock__ [member_link mutex..try_lock]]
|
|
[def __run_service__ `boost::fibers::asio::run_svc()`]
|
|
[def __shared_future_get__ [member_link shared_future..get]]
|
|
[def __sleep_for__ [ns_function_link this_fiber..sleep_for]]
|
|
[def __sleep_until__ [ns_function_link this_fiber..sleep_until]]
|
|
[def __yield_context__ ['boost::asio::yield_context]]
|
|
[def __yield_fiber__ ['boost::fibers::asio::yield_context]]
|
|
[def __yield__ [ns_function_link this_fiber..yield]]
|
|
|
|
[def __lock__ `lock()`]
|
|
[def __try_lock_for__ `try_lock_for()`]
|
|
[def __try_lock__ `try_lock()`]
|
|
[def __try_lock_until__ `try_lock_until()`]
|
|
[def __unlock__ `unlock()`]
|
|
|
|
|
|
[include overview.qbk]
|
|
[include fiber.qbk]
|
|
[include scheduling.qbk]
|
|
[include stack.qbk]
|
|
[#synchronization]
|
|
[section:synchronization Synchronization]
|
|
|
|
In general, __boost_fiber__ synchronization objects can neither be moved nor
|
|
copied. A synchronization object acts as a mutually-agreed rendezvous point
|
|
between different fibers. If such an object were copied somewhere else, the
|
|
new copy would have no consumers. If such an object were ['moved] somewhere
|
|
else, leaving the original instance in an unspecified state, existing
|
|
consumers would behave strangely.
|
|
|
|
The fiber synchronization objects provided by this library will, by default,
|
|
safely synchronize fibers running on different threads. However, this level of
|
|
synchronization can be removed (for performance) by building the library with
|
|
[*`BOOST_FIBERS_NO_ATOMICS`] defined. When the library is built with that macro,
|
|
you must ensure that all the fibers referencing a particular synchronization
|
|
object are running in the same thread.
|
|
|
|
[include mutexes.qbk]
|
|
[include condition_variables.qbk]
|
|
[include barrier.qbk]
|
|
[section:channels Channels]
|
|
A channel is a model to communicate and synchronize `Threads of Execution`
|
|
[footnote The smallest ordered sequence of instructions that can be managed
|
|
independently by a scheduler is called a `Thread of Execution`.] via message
|
|
passing.
|
|
|
|
[#class_channel_op_status]
|
|
[heading Enumeration `channel_op_status`]
|
|
|
|
channel operations return the state of the channel.
|
|
|
|
enum class channel_op_status {
|
|
success,
|
|
empty,
|
|
full,
|
|
closed,
|
|
timeout
|
|
};
|
|
|
|
[heading `success`]
|
|
[variablelist
|
|
[[Effects:] [Operation was successful.]]
|
|
]
|
|
|
|
[heading `empty`]
|
|
[variablelist
|
|
[[Effects:] [channel is empty, operation failed.]]
|
|
]
|
|
|
|
[heading `full`]
|
|
[variablelist
|
|
[[Effects:] [channel is full, operation failed.]]
|
|
]
|
|
|
|
[heading `closed`]
|
|
[variablelist
|
|
[[Effects:] [channel is closed, operation failed.]]
|
|
]
|
|
|
|
[heading `timeout`]
|
|
[variablelist
|
|
[[Effects:] [The operation did not become ready before specified timeout elapsed.]]
|
|
]
|
|
|
|
[include buffered_channel.qbk]
|
|
[include unbuffered_channel.qbk]
|
|
|
|
[endsect]
|
|
[include futures.qbk]
|
|
[endsect]
|
|
[include fls.qbk]
|
|
[/[include asio.qbk]]
|
|
[include migration.qbk]
|
|
[include callbacks.qbk]
|
|
[include nonblocking.qbk]
|
|
[include when_any.qbk]
|
|
[include integration.qbk]
|
|
[include speculative.qbk]
|
|
[include numa.qbk]
|
|
[section GPU computing]
|
|
[include cuda.qbk]
|
|
[include hip.qbk]
|
|
[endsect]
|
|
[include worker.qbk]
|
|
[include performance.qbk]
|
|
[include tuning.qbk]
|
|
[include customization.qbk]
|
|
[include rationale.qbk]
|
|
[include acknowledgements.qbk]
|