EQ2EMu/EQ2/source/depends/boost_1_72_0/libs/fiber/doc/fibers.qbk

[/
          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]