mirror of
https://github.com/boostorg/fiber.git
synced 2026-02-12 12:02:54 +00:00
8372 lines
489 KiB
XML
8372 lines
489 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
|
<library id="fiber" name="Fiber" dirname="fiber" last-revision="$Date: 2015/08/12 17:39:56 $"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<libraryinfo>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Oliver</firstname> <surname>Kowalke</surname>
|
|
</author>
|
|
</authorgroup>
|
|
<copyright>
|
|
<year>2013</year> <holder>Oliver Kowalke</holder>
|
|
</copyright>
|
|
<legalnotice id="fiber.legal">
|
|
<para>
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
file LICENSE_1_0.txt or copy at <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>)
|
|
</para>
|
|
</legalnotice>
|
|
<librarypurpose>
|
|
C++ Library to cooperatively schedule and synchronize micro-threads
|
|
</librarypurpose>
|
|
<librarycategory name="category:text"></librarycategory>
|
|
</libraryinfo>
|
|
<title>Fiber</title>
|
|
<section id="fiber.overview">
|
|
<title><link linkend="fiber.overview">Overview</link></title>
|
|
<para>
|
|
<emphasis role="bold">Boost.Fiber</emphasis> provides a framework for micro-/userland-threads
|
|
(fibers) scheduled cooperatively. The API contains classes and functions to
|
|
manage and synchronize fibers similiarly to <ulink url="boost:/libs/thread/index.html">Boost.Thread</ulink>.
|
|
</para>
|
|
<para>
|
|
Each fiber has its own stack.
|
|
</para>
|
|
<para>
|
|
A fiber can save the current execution state, including all registers and CPU
|
|
flags, the instruction pointer, and the stack pointer and later restore this
|
|
state. The idea is to have multiple execution paths running on a single thread
|
|
using cooperative scheduling (versus threads, which are preemptively scheduled).
|
|
The running fiber decides explicitly when it should yield to allow another
|
|
fiber to run (context switching). <emphasis role="bold">Boost.Fiber</emphasis>
|
|
internally uses <ulink url="boost:/libs/context/doc/html/context/econtext.html"><emphasis>execution_context</emphasis></ulink>
|
|
from <ulink url="boost:/libs/context/index.html">Boost.Context</ulink>; the
|
|
classes in this library manage, schedule and, when needed, synchronize those
|
|
execution contexts. A context switch between threads usually costs thousands
|
|
of CPU cycles on x86, compared to a fiber switch with less than a hundred cycles.
|
|
A fiber can only run on a single thread at any point in time.
|
|
</para>
|
|
<para>
|
|
In order to use the classes and functions described here, you can either include
|
|
the specific headers specified by the descriptions of each class or function,
|
|
or include the master library header:
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">all</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
</programlisting>
|
|
<para>
|
|
which includes all the other headers in turn.
|
|
</para>
|
|
<para>
|
|
The namespaces used are:
|
|
</para>
|
|
<programlisting><phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase>
|
|
<phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">this_fiber</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect3" id="fiber.overview.h0">
|
|
<phrase id="fiber.overview.fibers_and_threads"/><link linkend="fiber.overview.fibers_and_threads">Fibers
|
|
and Threads</link>
|
|
</bridgehead>
|
|
<para>
|
|
Control is cooperatively passed between fibers launched on a given thread.
|
|
At a given moment, on a given thread, at most one fiber is running.
|
|
</para>
|
|
<para>
|
|
Spawning additional fibers on a given thread does not increase your program's
|
|
utilization of hardware cores.
|
|
</para>
|
|
<para>
|
|
On the other hand, a fiber may safely access any resource exclusively owned
|
|
by its parent thread without explicitly needing to defend that resource against
|
|
concurrent access by other fibers on the same thread. You are already guaranteed
|
|
that no other fiber on that thread is concurrently touching that resource.
|
|
This can be particularly important when introducing concurrency in legacy code.
|
|
You can safely spawn fibers running old code, using asynchronous I/O to interleave
|
|
execution.
|
|
</para>
|
|
<para>
|
|
In effect, fibers provide a natural way to organize concurrent code based on
|
|
asynchronous I/O. Instead of chaining together completion handlers, code running
|
|
on a fiber can make what looks like a normal blocking function call. That call
|
|
can cheaply suspend the calling fiber, allowing other fibers on the same thread
|
|
to run. When the operation has completed, the suspended fiber resumes, without
|
|
having to explicitly save or restore its state. Its local stack variables persist
|
|
across the call.
|
|
</para>
|
|
<para>
|
|
A fiber launched on a particular thread will always run on that thread. A fiber
|
|
can count on thread-local storage; however that storage will be shared among
|
|
all fibers running on the same thread.
|
|
</para>
|
|
<para>
|
|
<anchor id="cross_thread_sync"/>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 <code><phrase role="identifier">BOOST_FIBERS_NO_ATOMICS</phrase></code>
|
|
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. Please see <link linkend="synchronization">synchronization</link>.
|
|
</para>
|
|
<para>
|
|
For fiber-local storage, please see <link linkend="class_fiber_specific_ptr"> <code>fiber_specific_ptr</code></link>.
|
|
</para>
|
|
<anchor id="blocking"/>
|
|
<bridgehead renderas="sect3" id="fiber.overview.h1">
|
|
<phrase id="fiber.overview.blocking"/><link linkend="fiber.overview.blocking">Blocking</link>
|
|
</bridgehead>
|
|
<para>
|
|
Normally, when this documentation states that a particular fiber <emphasis>blocks</emphasis>,
|
|
it means that it yields control, allowing other fibers on the same thread to
|
|
run. The synchronization mechanisms provided by <emphasis role="bold">Boost.Fiber</emphasis>
|
|
have this behavior.
|
|
</para>
|
|
<para>
|
|
A fiber may, of course, use normal thread synchronization mechanisms; however
|
|
a fiber that invokes any of these mechanisms will block its entire thread,
|
|
preventing any other fiber from running on that thread in the meantime. For
|
|
instance, when a fiber wants to wait for a value from another fiber in the
|
|
same thread, using <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">future</phrase></code> would be unfortunate: <code><phrase
|
|
role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">get</phrase><phrase role="special">()</phrase></code>
|
|
would block the whole thread, preventing the other fiber from delivering its
|
|
value. Use <link linkend="class_future"> <code>future<></code></link> instead.
|
|
</para>
|
|
<para>
|
|
Similarly, a fiber that invokes a normal blocking I/O operation will block
|
|
its entire thread. Fiber authors are encouraged to consistently use asynchronous
|
|
I/O. <ulink url="boost:/libs/asio/index.html">Boost.Asio</ulink> explicitly
|
|
supports fibers; other asynchronous I/O operations can straightforwardly be
|
|
adapted for <emphasis role="bold">Boost.Fiber</emphasis>.
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
This library is <emphasis>not</emphasis> an official Boost library.
|
|
</para>
|
|
</warning>
|
|
<para>
|
|
<emphasis role="bold">Boost.Fiber</emphasis> depends upon <ulink url="boost:/libs/context/index.html">Boost.Context</ulink>.
|
|
Boost version 1.58.0 or greater is required.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
This library is C++14-only!
|
|
</para>
|
|
</note>
|
|
</section>
|
|
<section id="fiber.fiber_mgmt">
|
|
<title><link linkend="fiber.fiber_mgmt">Fiber management</link></title>
|
|
<bridgehead renderas="sect3" id="fiber.fiber_mgmt.h0">
|
|
<phrase id="fiber.fiber_mgmt.synopsis"/><link linkend="fiber.fiber_mgmt.synopsis">Synopsis</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">all</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">fiber</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">l</phrase><phrase role="special">,</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">r</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="identifier">l</phrase><phrase role="special">,</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="identifier">r</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">struct</phrase> <phrase role="identifier">sched_algorithm</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">struct</phrase> <phrase role="identifier">sched_algorithm_with_properties</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">round_robin</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">set_scheduling_algorithm</phrase><phrase role="special">(</phrase> <phrase role="identifier">sched_algorithm</phrase> <phrase role="special">*</phrase> <phrase role="identifier">al</phrase><phrase role="special">)</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">ready_fibers</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">wait_interval</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">wait_interval</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="identifier">wait_interval</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="special">}</phrase>
|
|
|
|
<phrase role="keyword">namespace</phrase> <phrase role="identifier">this_fiber</phrase> <phrase role="special">{</phrase>
|
|
|
|
<phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase> <phrase role="identifier">get_id</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">yield</phrase><phrase role="special">();</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">sleep_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">sleep_time</phrase><phrase role="special">)</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">sleep_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">interruption_point</phrase><phrase role="special">();</phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">interruption_requested</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">interruption_enabled</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">disable_interruption</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">restore_interruption</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="special">}}</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect3" id="fiber.fiber_mgmt.h1">
|
|
<phrase id="fiber.fiber_mgmt.tutorial"/><link linkend="fiber.fiber_mgmt.tutorial">Tutorial</link>
|
|
</bridgehead>
|
|
<para>
|
|
Each <link linkend="class_fiber"> <code>fiber</code></link> represents a micro-thread which will be launched and managed
|
|
cooperatively by a scheduler. Objects of type <link linkend="class_fiber"> <code>fiber</code></link> are move-only.
|
|
</para>
|
|
<programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f1</phrase><phrase role="special">;</phrase> <phrase role="comment">// not-a-fiber</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">f</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f2</phrase><phrase role="special">(</phrase> <phrase role="identifier">some_fn</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="identifier">f1</phrase> <phrase role="special">=</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase> <phrase role="identifier">f2</phrase><phrase role="special">);</phrase> <phrase role="comment">// f2 moved to f1</phrase>
|
|
<phrase role="special">}</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect3" id="fiber.fiber_mgmt.h2">
|
|
<phrase id="fiber.fiber_mgmt.launching"/><link linkend="fiber.fiber_mgmt.launching">Launching</link>
|
|
</bridgehead>
|
|
<para>
|
|
A new fiber is launched by passing an object of a callable type that can be
|
|
invoked with no parameters. If the object must not (or cannot) be copied, then
|
|
<emphasis>std::ref</emphasis> can be used to pass in a reference to the function
|
|
object. In this case, the user must ensure that the referenced object outlives
|
|
the newly-created fiber.
|
|
</para>
|
|
<programlisting><phrase role="keyword">struct</phrase> <phrase role="identifier">callable</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="keyword">operator</phrase><phrase role="special">()();</phrase>
|
|
<phrase role="special">};</phrase>
|
|
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">copies_are_safe</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="identifier">callable</phrase> <phrase role="identifier">x</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">return</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">x</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">}</phrase> <phrase role="comment">// x is destroyed, but the newly-created fiber has a copy, so this is OK</phrase>
|
|
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">oops</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="identifier">callable</phrase> <phrase role="identifier">x</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">return</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ref</phrase><phrase role="special">(</phrase> <phrase role="identifier">x</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase>
|
|
<phrase role="special">}</phrase> <phrase role="comment">// x is destroyed, but the newly-created fiber still has a reference</phrase>
|
|
<phrase role="comment">// this leads to undefined behaviour</phrase>
|
|
</programlisting>
|
|
<para>
|
|
The spawned <link linkend="class_fiber"> <code>fiber</code></link> is enqueued in the list of ready-to-run fibers
|
|
at construction.
|
|
</para>
|
|
<bridgehead renderas="sect3" id="fiber.fiber_mgmt.h3">
|
|
<phrase id="fiber.fiber_mgmt.exceptions"/><link linkend="fiber.fiber_mgmt.exceptions">Exceptions</link>
|
|
</bridgehead>
|
|
<para>
|
|
An exception escaping from the function or callable object passed to the <link linkend="class_fiber"> <code>fiber</code></link>
|
|
constructor
|
|
calls <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">terminate</phrase><phrase role="special">()</phrase></code>.
|
|
If you need to know which exception was thrown, use <link linkend="class_future"> <code>future<></code></link> and
|
|
<link linkend="class_packaged_task"> <code>packaged_task<></code></link>.
|
|
</para>
|
|
<bridgehead renderas="sect3" id="fiber.fiber_mgmt.h4">
|
|
<phrase id="fiber.fiber_mgmt.detaching"/><link linkend="fiber.fiber_mgmt.detaching">Detaching</link>
|
|
</bridgehead>
|
|
<para>
|
|
A <link linkend="class_fiber"> <code>fiber</code></link> can be detached by explicitly invoking the <link linkend="fiber_detach"> <code>fiber::detach()</code></link> member
|
|
function. After <link linkend="fiber_detach"> <code>fiber::detach()</code></link> is called on a fiber object, that
|
|
object represents <emphasis>not-a-fiber</emphasis>. The fiber object may then
|
|
safely be destroyed.
|
|
</para>
|
|
<programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">some_fn</phrase><phrase role="special">).</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect3" id="fiber.fiber_mgmt.h5">
|
|
<phrase id="fiber.fiber_mgmt.joining"/><link linkend="fiber.fiber_mgmt.joining">Joining</link>
|
|
</bridgehead>
|
|
<para>
|
|
In order to wait for a fiber to finish, the <link linkend="fiber_join"> <code>fiber::join()</code></link> member function
|
|
of the <link linkend="class_fiber"> <code>fiber</code></link> object can be used. <link linkend="fiber_join"> <code>fiber::join()</code></link> will block
|
|
until the <link linkend="class_fiber"> <code>fiber</code></link> object has completed. If the <link linkend="class_fiber"> <code>fiber</code></link> has
|
|
already completed then <link linkend="fiber_join"> <code>fiber::join()</code></link> returns immediately.
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">some_fn</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="special">...</phrase>
|
|
<phrase role="special">}</phrase>
|
|
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f</phrase><phrase role="special">(</phrase> <phrase role="identifier">some_fn</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">...</phrase>
|
|
<phrase role="identifier">f</phrase><phrase role="special">.</phrase><phrase role="identifier">join</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<para>
|
|
If the fiber has already completed, then <link linkend="fiber_join"> <code>fiber::join()</code></link> returns immediately
|
|
and the joined <link linkend="class_fiber"> <code>fiber</code></link> object becomes <emphasis>not-a-fiber</emphasis>.
|
|
</para>
|
|
<bridgehead renderas="sect3" id="fiber.fiber_mgmt.h6">
|
|
<phrase id="fiber.fiber_mgmt.destruction"/><link linkend="fiber.fiber_mgmt.destruction">Destruction</link>
|
|
</bridgehead>
|
|
<para>
|
|
When a <link linkend="class_fiber"> <code>fiber</code></link> object representing a valid execution context is destroyed,
|
|
the program terminates if the fiber is <link linkend="fiber_joinable"> <code>fiber::joinable()</code></link>. If
|
|
you intend the fiber to outlive the <link linkend="class_fiber"> <code>fiber</code></link> object that launched it,
|
|
use the <link linkend="fiber_detach"> <code>fiber::detach()</code></link>
|
|
method.
|
|
</para>
|
|
<programlisting><phrase role="special">{</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f</phrase><phrase role="special">(</phrase> <phrase role="identifier">some_fn</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">}</phrase> <phrase role="comment">// std::terminate() will be called</phrase>
|
|
|
|
<phrase role="special">{</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f</phrase><phrase role="special">(</phrase><phrase role="identifier">some_fn</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">f</phrase><phrase role="special">.</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">}</phrase> <phrase role="comment">// okay, program continues</phrase>
|
|
</programlisting>
|
|
<anchor id="interruption"/>
|
|
<bridgehead renderas="sect3" id="fiber.fiber_mgmt.h7">
|
|
<phrase id="fiber.fiber_mgmt.interruption"/><link linkend="fiber.fiber_mgmt.interruption">Interruption</link>
|
|
</bridgehead>
|
|
<para>
|
|
A valid fiber can be interrupted by invoking its <link linkend="fiber_interrupt"> <code>fiber::interrupt()</code></link> member
|
|
function. The next time that fiber executes one of the specific <link linkend="interruption"><emphasis>interruption-points</emphasis></link>
|
|
with interruption enabled, a <code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
exception will be thrown. If this exception is not caught, the fiber will be
|
|
terminated, its stack unwound, its stack objects properly destroyed.
|
|
</para>
|
|
<para>
|
|
With <link linkend="class_disable_interruption"> <code>disable_interruption</code></link> a fiber can avoid being
|
|
interrupted.
|
|
</para>
|
|
<programlisting><phrase role="comment">// interruption enabled at this point</phrase>
|
|
<phrase role="special">{</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">disable_interruption</phrase> <phrase role="identifier">di1</phrase><phrase role="special">;</phrase>
|
|
<phrase role="comment">// interruption disabled</phrase>
|
|
<phrase role="special">{</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="keyword">this</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">disable_interruption</phrase> <phrase role="identifier">di2</phrase><phrase role="special">;</phrase>
|
|
<phrase role="comment">// interruption still disabled</phrase>
|
|
<phrase role="special">}</phrase> <phrase role="comment">// di2 destroyed; interruption state restored</phrase>
|
|
<phrase role="comment">// interruption still disabled</phrase>
|
|
<phrase role="special">}</phrase> <phrase role="comment">// di destroyed; interruption state restored</phrase>
|
|
<phrase role="comment">// interruption enabled</phrase>
|
|
</programlisting>
|
|
<para>
|
|
At any point, the interruption state for the current thread can be queried
|
|
by calling <link linkend="this_fiber_interruption_enabled"> <code>this_fiber::interruption_enabled()</code></link>.
|
|
The following <link linkend="interruption"><emphasis>interruption-points</emphasis></link>
|
|
are defined and will throw <code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
if <link linkend="this_fiber_interruption_requested"> <code>this_fiber::interruption_requested()</code></link> and
|
|
<link linkend="this_fiber_interruption_enabled"> <code>this_fiber::interruption_enabled()</code></link>.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="fiber_join"> <code>fiber::join()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="barrier_wait"> <code>barrier::wait()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="condition_variable_wait"> <code>condition_variable::wait()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="condition_variable_wait_for"> <code>condition_variable::wait_for()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="condition_variable_wait_until"> <code>condition_variable::wait_until()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="mutex_lock"> <code>mutex::lock()</code></link> ( <link linkend="class_recursive_mutex"> <code>recursive_mutex</code></link>, <link linkend="class_recursive_timed_mutex"> <code>recursive_timed_mutex</code></link>,
|
|
<link linkend="class_timed_mutex"> <code>timed_mutex</code></link>)
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="mutex_try_lock"> <code>mutex::try_lock()</code></link> ( <link linkend="class_recursive_mutex"> <code>recursive_mutex</code></link>,
|
|
<link linkend="class_recursive_timed_mutex"> <code>recursive_timed_mutex</code></link>, <link linkend="class_timed_mutex"> <code>timed_mutex</code></link>)
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="this_fiber_sleep_for"> <code>this_fiber::sleep_for()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="this_fiber_sleep_until"> <code>this_fiber::sleep_until()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="this_fiber_interruption_point"> <code>this_fiber::interruption_point()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="bounded_channel_push"> <code>bounded_channel::push()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="bounded_channel_try_push"> <code>bounded_channel::try_push()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="bounded_channel_push_wait_for"> <code>bounded_channel::push_wait_for()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="bounded_channel_push_wait_until"> <code>bounded_channel::push_wait_until()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="bounded_channel_pop"> <code>bounded_channel::pop()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="bounded_channel_try_pop"> <code>bounded_channel::try_pop()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="bounded_channel_value_pop"> <code>bounded_channel::value_pop()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="bounded_channel_pop_wait_for"> <code>bounded_channel::pop_wait_for()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="bounded_channel_pop_wait_until"> <code>bounded_channel::pop_wait_until()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="unbounded_channel_push"> <code>unbounded_channel::push()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="unbounded_channel_pop"> <code>unbounded_channel::pop()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="unbounded_channel_try_pop"> <code>unbounded_channel::try_pop()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="unbounded_channel_value_pop"> <code>unbounded_channel::value_pop()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="unbounded_channel_pop_wait_for"> <code>unbounded_channel::pop_wait_for()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="unbounded_channel_pop_wait_until"> <code>unbounded_channel::pop_wait_until()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="future_wait"> <code>future::wait()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="future_get"> <code>future::get()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="future_get_exception_ptr"> <code>future::get_exception_ptr()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="shared_future_wait"> <code>shared_future::wait()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="shared_future_get"> <code>shared_future::get()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="shared_future_get_exception_ptr"> <code>shared_future::get_exception_ptr()</code></link>
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<anchor id="class_fiber_id"/>
|
|
<bridgehead renderas="sect3" id="fiber.fiber_mgmt.h8">
|
|
<phrase id="fiber.fiber_mgmt.fiber_ids"/><link linkend="fiber.fiber_mgmt.fiber_ids">Fiber
|
|
IDs</link>
|
|
</bridgehead>
|
|
<para>
|
|
Objects of class <link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">id</phrase></code></link> can be
|
|
used to identify fibers. Each running <link linkend="class_fiber"> <code>fiber</code></link> has a unique <link linkend="class_fiber_id"><code><phrase
|
|
role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase></code></link> obtainable
|
|
from the corresponding <link linkend="class_fiber"> <code>fiber</code></link>
|
|
by calling the <link linkend="fiber_get_id"> <code>fiber::get_id()</code></link> member
|
|
function. Objects of class <link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">id</phrase></code></link> can be
|
|
copied, and used as keys in associative containers: the full range of comparison
|
|
operators is provided. They can also be written to an output stream using the
|
|
stream insertion operator, though the output format is unspecified.
|
|
</para>
|
|
<para>
|
|
Each instance of <link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">id</phrase></code></link> either
|
|
refers to some fiber, or <emphasis>not-a-fiber</emphasis>. Instances that refer
|
|
to <emphasis>not-a-fiber</emphasis> compare equal to each other, but not equal
|
|
to any instances that refer to an actual fiber. The comparison operators on
|
|
<link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">id</phrase></code></link> yield a total order for every non-equal
|
|
<link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">id</phrase></code></link>.
|
|
</para>
|
|
<section id="fiber.fiber_mgmt.fiber">
|
|
<title><anchor id="class_fiber"/><link linkend="fiber.fiber_mgmt.fiber">Class
|
|
<code><phrase role="identifier">fiber</phrase></code></link></title>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">id</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">fiber</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">explicit</phrase> <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">StackAllocator</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">explicit</phrase> <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase><phrase role="special">,</phrase> <phrase role="identifier">StackAllocator</phrase> <phrase role="identifier">salloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="special">~</phrase><phrase role="identifier">fiber</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">explicit</phrase> <phrase role="keyword">operator</phrase> <phrase role="keyword">bool</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">!()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">joinable</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">id</phrase> <phrase role="identifier">get_id</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">detach</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">join</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">interrupt</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">};</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">l</phrase><phrase role="special">,</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">r</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="identifier">l</phrase><phrase role="special">,</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="identifier">r</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">set_scheduling_algorithm</phrase><phrase role="special">(</phrase> <phrase role="identifier">sched_algorithm</phrase> <phrase role="special">*</phrase> <phrase role="identifier">al</phrase><phrase role="special">)</phrase>
|
|
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">ready_fibers</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">wait_interval</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">wait_interval</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="identifier">wait_interval</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect4" id="fiber.fiber_mgmt.fiber.h0">
|
|
<phrase id="fiber.fiber_mgmt.fiber.default_constructor"/><link linkend="fiber.fiber_mgmt.fiber.default_constructor">Default
|
|
constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">fiber</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Constructs a <link linkend="class_fiber"> <code>fiber</code></link> instance that refers to <emphasis>not-a-fiber</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">get_id</phrase><phrase role="special">()</phrase>
|
|
<phrase role="special">==</phrase> <phrase role="identifier">fiber</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">id</phrase><phrase
|
|
role="special">()</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect4" id="fiber.fiber_mgmt.fiber.h1">
|
|
<phrase id="fiber.fiber_mgmt.fiber.constructor"/><link linkend="fiber.fiber_mgmt.fiber.constructor">Constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">explicit</phrase> <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">StackAllocator</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">explicit</phrase> <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase><phrase role="special">,</phrase> <phrase role="identifier">StackAllocator</phrase> <phrase role="identifier">salloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Preconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">Fn</phrase></code> must be copyable
|
|
or movable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fn</phrase></code> is copied or moved
|
|
into internal storage for access by the new fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
refers to the newly created fiber of execution.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_exception</phrase></code> if
|
|
an error occurs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
StackAllocator is required to allocate a stack for the internal <ulink
|
|
url="boost:/libs/context/doc/html/context/econtext.html"><emphasis>execution_context</emphasis></ulink>.
|
|
If StackAllocator is not explicitly passed, a <link linkend="class_fixedsize_stack"> <code>fixedsize_stack</code></link> is
|
|
used by default.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>See also:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="stack">stack</link>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect4" id="fiber.fiber_mgmt.fiber.h2">
|
|
<phrase id="fiber.fiber_mgmt.fiber.move_constructor"/><link linkend="fiber.fiber_mgmt.fiber.move_constructor">Move
|
|
constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Transfers ownership of the fiber managed by <code><phrase role="identifier">other</phrase></code>
|
|
to the newly constructed <link linkend="class_fiber"> <code>fiber</code></link> instance.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">other</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">get_id</phrase><phrase role="special">()</phrase>
|
|
<phrase role="special">==</phrase> <phrase role="identifier">fiber</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">id</phrase><phrase
|
|
role="special">()</phrase></code> and <code><phrase role="identifier">get_id</phrase><phrase
|
|
role="special">()</phrase></code> returns the value of <code><phrase
|
|
role="identifier">other</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">get_id</phrase><phrase role="special">()</phrase></code>
|
|
prior to the construction
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect4" id="fiber.fiber_mgmt.fiber.h3">
|
|
<phrase id="fiber.fiber_mgmt.fiber.move_assignment_operator"/><link linkend="fiber.fiber_mgmt.fiber.move_assignment_operator">Move
|
|
assignment operator</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Transfers ownership of the fiber managed by <code><phrase role="identifier">other</phrase></code>
|
|
(if any) to <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">other</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">get_id</phrase><phrase role="special">()</phrase>
|
|
<phrase role="special">==</phrase> <phrase role="identifier">fiber</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">id</phrase><phrase
|
|
role="special">()</phrase></code> and <code><phrase role="identifier">get_id</phrase><phrase
|
|
role="special">()</phrase></code> returns the value of <code><phrase
|
|
role="identifier">other</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">get_id</phrase><phrase role="special">()</phrase></code>
|
|
prior to the assignment.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect4" id="fiber.fiber_mgmt.fiber.h4">
|
|
<phrase id="fiber.fiber_mgmt.fiber.destructor"/><link linkend="fiber.fiber_mgmt.fiber.destructor">Destructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="special">~</phrase><phrase role="identifier">fiber</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
If the fiber is <link linkend="fiber_joinable"> <code>fiber::joinable()</code></link>, calls std::terminate.
|
|
Destroys <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
The programmer must ensure that the destructor is never executed while
|
|
the fiber is still <link linkend="fiber_joinable"> <code>fiber::joinable()</code></link>. Even if you know
|
|
(by calling <link linkend="fiber_operator bool"> <code>fiber::operator bool()</code></link>) that the fiber
|
|
has completed, you must still call either <link linkend="fiber_join"> <code>fiber::join()</code></link> or
|
|
<link linkend="fiber_detach"> <code>fiber::detach()</code></link> before destroying the <code><phrase role="identifier">fiber</phrase></code>
|
|
object.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_joinable_bridgehead">
|
|
<phrase id="fiber_joinable"/>
|
|
<link linkend="fiber_joinable">Member function <code>joinable</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">joinable</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
refers to a fiber of execution, which may or may not have completed;
|
|
otherwise <code><phrase role="keyword">false</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>See also:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="fiber_operator bool"> <code>fiber::operator bool()</code></link>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_join_bridgehead">
|
|
<phrase id="fiber_join"/>
|
|
<link linkend="fiber_join">Member function <code>join</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">join</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Preconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
the fiber is <link linkend="fiber_joinable"> <code>fiber::joinable()</code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
If <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
refers to a fiber of execution, waits for that fiber to complete.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
If <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
refers to a fiber of execution on entry, that fiber has completed.
|
|
<code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
no longer refers to any fiber of execution.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_interrupted</phrase></code> if
|
|
the current fiber is interrupted or <code><phrase role="identifier">system_error</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Error Conditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<emphasis role="bold">resource_deadlock_would_occur</emphasis>: if
|
|
<code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">get_id</phrase><phrase role="special">()</phrase>
|
|
<phrase role="special">==</phrase> <phrase role="identifier">boost</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">this_fiber</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">get_id</phrase><phrase
|
|
role="special">()</phrase></code>. <emphasis role="bold">invalid_argument</emphasis>:
|
|
if the fiber is not <link linkend="fiber_joinable"> <code>fiber::joinable()</code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Notes:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">join</phrase><phrase role="special">()</phrase></code>
|
|
is one of the predefined <link linkend="interruption"><emphasis>interruption-points</emphasis></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_detach_bridgehead">
|
|
<phrase id="fiber_detach"/>
|
|
<link linkend="fiber_detach">Member function <code>detach</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">detach</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Preconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
the fiber is <link linkend="fiber_joinable"> <code>fiber::joinable()</code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
The fiber of execution becomes detached, and no longer has an associated
|
|
<link linkend="class_fiber"> <code>fiber</code></link> object.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
no longer refers to any fiber of execution.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">system_error</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Error Conditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<emphasis role="bold">invalid_argument</emphasis>: if the fiber is
|
|
not <link linkend="fiber_joinable"> <code>fiber::joinable()</code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_get_id_bridgehead">
|
|
<phrase id="fiber_get_id"/>
|
|
<link linkend="fiber_get_id">Member function <code>get_id</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase> <phrase role="identifier">get_id</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
If <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
refers to a fiber of execution, an instance of <link linkend="class_fiber_id"><code><phrase
|
|
role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">id</phrase></code></link> that represents that fiber. Otherwise
|
|
returns a default-constructed <link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">id</phrase></code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>See also:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="this_fiber_get_id"> <code>this_fiber::get_id()</code></link>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_interrupt_bridgehead">
|
|
<phrase id="fiber_interrupt"/>
|
|
<link linkend="fiber_interrupt">Member function <code>interrupt</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">interrupt</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
If <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
refers to a fiber of execution, request that the fiber will be interrupted
|
|
the next time it enters one of the predefined <link linkend="interruption"><emphasis>interruption-points</emphasis></link>
|
|
with interruption enabled, or if it is currently <link linkend="blocking"><emphasis>blocked</emphasis></link>
|
|
in a call to one of the predefined <link linkend="interruption"><emphasis>interruption-points</emphasis></link>
|
|
with interruption enabled.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_properties_bridgehead">
|
|
<phrase id="fiber_properties"/>
|
|
<link linkend="fiber_properties">Templated member
|
|
function <code>properties</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Preconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
refers to a fiber of execution. <link linkend="set_scheduling_algorithm"> <code>set_scheduling_algorithm()</code></link> has
|
|
been called from this thread with a pointer to a (subclass) instance
|
|
of <link linkend="class_sched_algorithm_with_properties"> <code>sched_algorithm_with_properties<></code></link> with
|
|
the same template argument <code><phrase role="identifier">PROPS</phrase></code>.
|
|
<code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
has been scheduled for execution at least once.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
a reference to the scheduler properties instance for <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">bad_cast</phrase></code> if <code><phrase role="identifier">set_scheduling_algorithm</phrase><phrase
|
|
role="special">()</phrase></code> was passed a pointer to a <code><phrase
|
|
role="identifier">sched_algorithm_with_properties</phrase></code> subclass
|
|
with some other template parameter than <code><phrase role="identifier">PROPS</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="class_sched_algorithm_with_properties"> <code>sched_algorithm_with_properties<></code></link> provides
|
|
a way for a user-coded scheduler to associate extended properties,
|
|
such as priority, with a fiber instance. This method allows access
|
|
to those user-provided properties -- but only after this fiber has
|
|
been scheduled for the first time.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>See also:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="custom">custom</link>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_operator bool_bridgehead">
|
|
<phrase id="fiber_operator bool"/>
|
|
<link linkend="fiber_operator bool">Member
|
|
function <code>operator bool</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">explicit</phrase> <phrase role="keyword">operator</phrase> <phrase role="keyword">bool</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
refers to a fiber of execution which has not yet terminated, <code><phrase
|
|
role="keyword">false</phrase></code> otherwise. Compare to <link linkend="fiber_joinable"> <code>fiber::joinable()</code></link>,
|
|
which does not distinguish whether the referenced fiber of execution
|
|
is still running.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>See also:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="fiber_joinable"> <code>fiber::joinable()</code></link>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_operator_not_bridgehead">
|
|
<phrase id="fiber_operator_not"/>
|
|
<link linkend="fiber_operator_not">Member function
|
|
<code>operator!</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">!()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
does not refer to a fiber of execution or if its fiber of execution
|
|
has terminated, <code><phrase role="keyword">false</phrase></code>
|
|
otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>See also:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="fiber_operator bool"> <code>fiber::operator bool()</code></link>, <link linkend="fiber_joinable"> <code>fiber::joinable()</code></link>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_swap_bridgehead">
|
|
<phrase id="fiber_swap"/>
|
|
<link linkend="fiber_swap">Member function <code>swap</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Exchanges the fiber of execution associated with <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code> and <code><phrase role="identifier">other</phrase></code>,
|
|
so <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
becomes associated with the fiber formerly associated with <code><phrase
|
|
role="identifier">other</phrase></code>, and vice-versa.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">get_id</phrase><phrase role="special">()</phrase></code>
|
|
returns the same value as <code><phrase role="identifier">other</phrase><phrase
|
|
role="special">.</phrase><phrase role="identifier">get_id</phrase><phrase
|
|
role="special">()</phrase></code> prior to the call. <code><phrase
|
|
role="identifier">other</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">get_id</phrase><phrase role="special">()</phrase></code>
|
|
returns the same value as <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">get_id</phrase><phrase
|
|
role="special">()</phrase></code> prior to the call.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="swap_bridgehead">
|
|
<phrase id="swap"/>
|
|
<link linkend="swap">Non-member function <code>swap()</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="identifier">l</phrase><phrase role="special">,</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="identifier">r</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Same as <code><phrase role="identifier">l</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase
|
|
role="identifier">r</phrase><phrase role="special">)</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="set_scheduling_algorithm_bridgehead">
|
|
<phrase id="set_scheduling_algorithm"/>
|
|
<link linkend="set_scheduling_algorithm">Non-member
|
|
function <code>set_scheduling_algorithm()</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">set_scheduling_algorithm</phrase><phrase role="special">(</phrase> <phrase role="identifier">sched_algorithm</phrase><phrase role="special">*</phrase> <phrase role="identifier">scheduler</phrase> <phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Directs <emphasis role="bold">Boost.Fiber</emphasis> to use <code><phrase
|
|
role="identifier">scheduler</phrase></code>, which must be a concrete
|
|
subclass of <link linkend="class_sched_algorithm"> <code>sched_algorithm</code></link>, as the scheduling
|
|
algorithm for all fibers in the current thread.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
If you want a given thread to use a non-default scheduling algorithm,
|
|
make that thread call <code><phrase role="identifier">set_scheduling_algorithm</phrase><phrase
|
|
role="special">()</phrase></code> before any other <emphasis role="bold">Boost.Fiber</emphasis>
|
|
entry point. If no scheduler has been set for the current thread by
|
|
the time <emphasis role="bold">Boost.Fiber</emphasis> needs to use
|
|
it, the library will create a default <link linkend="class_round_robin"> <code>round_robin</code></link> instance
|
|
for this thread.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">set_scheduling_algorithm</phrase><phrase
|
|
role="special">()</phrase></code> does <emphasis>not</emphasis> take
|
|
ownership of the passed <code><phrase role="identifier">sched_algorithm</phrase><phrase
|
|
role="special">*</phrase></code>: <emphasis role="bold">Boost.Fiber</emphasis>
|
|
does not claim responsibility for the lifespan of the referenced <code><phrase
|
|
role="identifier">scheduler</phrase></code> object. The caller must
|
|
eventually destroy the passed <code><phrase role="identifier">scheduler</phrase></code>,
|
|
just as it must allocate it in the first place.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>See also:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="scheduling">scheduling</link>, <link linkend="custom">custom</link>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="ready_fibers_bridgehead">
|
|
<phrase id="ready_fibers"/>
|
|
<link linkend="ready_fibers">Non-member function <code>ready_fibers()</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">ready_fibers</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
Returns the amount of fibers ready to run.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="wait_interval_bridgehead">
|
|
<phrase id="wait_interval"/>
|
|
<link linkend="wait_interval">Non-member function <code>wait_interval()</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">wait_interval</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">wait_interval</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="identifier">wait_interval</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
Sets/returns the wait interval used to suspend the thread if no fibers
|
|
are ready to run.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Notes:</term>
|
|
<listitem>
|
|
<para>
|
|
This setting can be used to adjust the "niceness" of an idle
|
|
thread: a thread whose fibers are all currently blocked for various
|
|
reasons. A longer <code><phrase role="identifier">wait_interval</phrase><phrase
|
|
role="special">()</phrase></code> causes an idle thread to use less
|
|
CPU. The default for each thread, if not specified, is <code><phrase
|
|
role="identifier">std</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">milliseconds</phrase><phrase role="special">(</phrase><phrase
|
|
role="number">10</phrase><phrase role="special">)</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
<section id="fiber.fiber_mgmt.id">
|
|
<title><anchor id="class_id"/><link linkend="fiber.fiber_mgmt.id">Class fiber::id</link></title>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">id</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">id</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">==(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">!=(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">>(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><=(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">>=(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">charT</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">friend</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">basic_ostream</phrase><phrase role="special"><</phrase> <phrase role="identifier">charT</phrase><phrase role="special">,</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase>
|
|
<phrase role="keyword">operator</phrase><phrase role="special"><<(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">basic_ostream</phrase><phrase role="special"><</phrase> <phrase role="identifier">charT</phrase><phrase role="special">,</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> <phrase role="identifier">os</phrase><phrase role="special">,</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect4" id="fiber.fiber_mgmt.id.h0">
|
|
<phrase id="fiber.fiber_mgmt.id.constructor"/><link linkend="fiber.fiber_mgmt.id.constructor">Constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">id</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Represents an instance of <emphasis>not-a-fiber</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="id_operator_equal_bridgehead">
|
|
<phrase id="id_operator_equal"/>
|
|
<link linkend="id_operator_equal">Member function
|
|
<code>operator==</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">==(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
and <code><phrase role="identifier">other</phrase></code> represent
|
|
the same fiber, or both represent <emphasis>not-a-fiber</emphasis>,
|
|
<code><phrase role="keyword">false</phrase></code> otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="id_operator_not_equal_bridgehead">
|
|
<phrase id="id_operator_not_equal"/>
|
|
<link linkend="id_operator_not_equal">Member
|
|
function <code>operator!=</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">!=(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code>! (other == * this)</code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="id_operator_less_bridgehead">
|
|
<phrase id="id_operator_less"/>
|
|
<link linkend="id_operator_less">Member function
|
|
<code>operator<</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase> <phrase
|
|
role="special">!=</phrase> <phrase role="identifier">other</phrase></code>
|
|
is true and the implementation-defined total order of <code><phrase
|
|
role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">id</phrase></code> values places <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code> before <code><phrase role="identifier">other</phrase></code>,
|
|
false otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="id_operator_greater_bridgehead">
|
|
<phrase id="id_operator_greater"/>
|
|
<link linkend="id_operator_greater">Member
|
|
function <code>operator></code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">>(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">other</phrase> <phrase role="special"><</phrase>
|
|
<phrase role="special">*</phrase> <phrase role="keyword">this</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="id_operator_less_equal_bridgehead">
|
|
<phrase id="id_operator_less_equal"/>
|
|
<link linkend="id_operator_less_equal">Member
|
|
function <code>operator<=</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><=(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="special">!</phrase> <phrase role="special">(</phrase><phrase
|
|
role="identifier">other</phrase> <phrase role="special"><</phrase>
|
|
<phrase role="special">*</phrase> <phrase role="keyword">this</phrase><phrase
|
|
role="special">)</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="id_operator_greater_equal_bridgehead">
|
|
<phrase id="id_operator_greater_equal"/>
|
|
<link linkend="id_operator_greater_equal">Member
|
|
function <code>operator>=</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">>=(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="special">!</phrase> <phrase role="special">(*</phrase>
|
|
<phrase role="keyword">this</phrase> <phrase role="special"><</phrase>
|
|
<phrase role="identifier">other</phrase><phrase role="special">)</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect4" id="fiber.fiber_mgmt.id.h1">
|
|
<phrase id="fiber.fiber_mgmt.id.operator_lt__lt_"/><link linkend="fiber.fiber_mgmt.id.operator_lt__lt_">operator<<</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">charT</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">basic_ostream</phrase><phrase role="special"><</phrase> <phrase role="identifier">charT</phrase><phrase role="special">,</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase>
|
|
<phrase role="keyword">operator</phrase><phrase role="special"><<(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">basic_ostream</phrase><phrase role="special"><</phrase> <phrase role="identifier">charT</phrase><phrase role="special">,</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> <phrase role="identifier">os</phrase><phrase role="special">,</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Efects:</term>
|
|
<listitem>
|
|
<para>
|
|
Writes the representation of <code><phrase role="identifier">other</phrase></code>
|
|
to stream <code><phrase role="identifier">os</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">os</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
<section id="fiber.fiber_mgmt.this_fiber">
|
|
<title><link linkend="fiber.fiber_mgmt.this_fiber">Namespace this_fiber</link></title>
|
|
<programlisting><phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">namespace</phrase> <phrase role="identifier">this_fiber</phrase> <phrase role="special">{</phrase>
|
|
|
|
<phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase> <phrase role="identifier">get_id</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">yield</phrase><phrase role="special">();</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">sleep_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">)</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">sleep_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">interruption_point</phrase><phrase role="special">();</phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">interruption_requested</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">interruption_enabled</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">disable_interruption</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">restore_interruption</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="special">}}</phrase>
|
|
</programlisting>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="this_fiber_get_id_bridgehead">
|
|
<phrase id="this_fiber_get_id"/>
|
|
<link linkend="this_fiber_get_id">Non-member
|
|
function <code>this_fiber::get_id()</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">operations</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase> <phrase role="identifier">get_id</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
An instance of <link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">id</phrase></code></link> that
|
|
represents the currently executing fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="this_fiber_sleep_until_bridgehead">
|
|
<phrase id="this_fiber_sleep_until"/>
|
|
<link linkend="this_fiber_sleep_until">Non-member
|
|
function <code>this_fiber::sleep_until()</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">operations</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">sleep_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">)</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Suspends the current fiber until the time point specified by <code><phrase
|
|
role="identifier">abs_time</phrase></code> has been reached.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_interrupted</phrase></code> if
|
|
the current fiber is interrupted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">sleep_until</phrase><phrase role="special">()</phrase></code>
|
|
is one of the predefined <link linkend="interruption"><emphasis>interruption-points</emphasis></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
The current fiber will not resume before <code><phrase role="identifier">abs_time</phrase></code>,
|
|
but there are no guarantees about how soon after <code><phrase role="identifier">abs_time</phrase></code>
|
|
it might resume.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="this_fiber_sleep_for_bridgehead">
|
|
<phrase id="this_fiber_sleep_for"/>
|
|
<link linkend="this_fiber_sleep_for">Non-member
|
|
function <code>this_fiber::sleep_for()</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">operations</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">sleep_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">rel_time</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Suspends the current fiber until the time duration specified by <code><phrase
|
|
role="identifier">rel_time</phrase></code> has elapsed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Any exceptions thrown by operations of <code><phrase role="identifier">std</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">duration</phrase><phrase
|
|
role="special"><</phrase><phrase role="identifier">Rep</phrase><phrase
|
|
role="special">,</phrase> <phrase role="identifier">Period</phrase><phrase
|
|
role="special">></phrase></code>. <code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
if the current fiber is interrupted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">sleep_for</phrase><phrase role="special">()</phrase></code>
|
|
is one of the predefined <link linkend="interruption"><emphasis>interruption-points</emphasis></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
The current fiber will not resume before <code><phrase role="identifier">rel_time</phrase></code>
|
|
has elapsed, but there are no guarantees about how soon after that
|
|
it might resume.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="this_fiber_yield_bridgehead">
|
|
<phrase id="this_fiber_yield"/>
|
|
<link linkend="this_fiber_yield">Non-member function
|
|
<code>this_fiber::yield()</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">operations</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">yield</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Reliquishes execution control, allowing other fibers to run.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_resource_error</phrase></code>
|
|
if an error occurs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">yield</phrase><phrase role="special">()</phrase></code>
|
|
is <emphasis>not</emphasis> an interruption point. A fiber that calls
|
|
<code><phrase role="identifier">yield</phrase><phrase role="special">()</phrase></code>
|
|
is not suspended: it is immediately passed to the scheduler as ready
|
|
to run.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="this_fiber_properties_bridgehead">
|
|
<phrase id="this_fiber_properties"/>
|
|
<link linkend="this_fiber_properties">Non-member
|
|
function <code>this_fiber::properties()</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">operations</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Preconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="set_scheduling_algorithm"> <code>set_scheduling_algorithm()</code></link> has been called from
|
|
this thread with a pointer to a (subclass) instance of <link linkend="class_sched_algorithm_with_properties"> <code>sched_algorithm_with_properties<></code></link> with
|
|
the same template argument <code><phrase role="identifier">PROPS</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
a reference to the scheduler properties instance for the currently
|
|
running fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">bad_cast</phrase></code> if <code><phrase role="identifier">set_scheduling_algorithm</phrase><phrase
|
|
role="special">()</phrase></code> was passed a pointer to a <code><phrase
|
|
role="identifier">sched_algorithm_with_properties</phrase></code> subclass
|
|
with some other template parameter than <code><phrase role="identifier">PROPS</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="class_sched_algorithm_with_properties"> <code>sched_algorithm_with_properties<></code></link> provides
|
|
a way for a user-coded scheduler to associate extended properties,
|
|
such as priority, with a fiber instance. This function allows access
|
|
to those user-provided properties.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>See also:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="custom">custom</link>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="this_fiber_interruption_point_bridgehead">
|
|
<phrase id="this_fiber_interruption_point"/>
|
|
<link linkend="this_fiber_interruption_point">Non-member
|
|
function <code>this_fiber::interruption_point()</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">interruption</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">interruption_point</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Check to see if the current fiber has been interrupted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_interrupted</phrase></code> if
|
|
<link linkend="this_fiber_interruption_enabled"> <code>this_fiber::interruption_enabled()</code></link> and
|
|
<link linkend="this_fiber_interruption_requested"> <code>this_fiber::interruption_requested()</code></link> both
|
|
return <code><phrase role="keyword">true</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="this_fiber_interruption_requested_bridgehead">
|
|
<phrase id="this_fiber_interruption_requested"/>
|
|
<link linkend="this_fiber_interruption_requested">Non-member
|
|
function <code>this_fiber::interruption_requested()</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">interruption</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">interruption_requested</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if interruption has
|
|
been requested for the current fiber, <code><phrase role="keyword">false</phrase></code>
|
|
otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="this_fiber_interruption_enabled_bridgehead">
|
|
<phrase id="this_fiber_interruption_enabled"/>
|
|
<link linkend="this_fiber_interruption_enabled">Non-member
|
|
function <code>this_fiber::interruption_enabled()</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">interruption</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">interruption_enabled</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if interruption is
|
|
enabled for the current fiber, <code><phrase role="keyword">false</phrase></code>
|
|
otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
Interruption is enabled by default.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_disable_interruption_bridgehead">
|
|
<phrase id="class_disable_interruption"/>
|
|
<link linkend="class_disable_interruption">Class
|
|
<code>disable_interruption</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">interruption</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">disable_interruption</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">disable_interruption</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">~</phrase><phrase role="identifier">disable_interruption</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">disable_interruption</phrase><phrase role="special">(</phrase><phrase role="keyword">const</phrase> <phrase role="identifier">disable_interruption</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">disable_interruption</phrase><phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase><phrase role="keyword">const</phrase> <phrase role="identifier">disable_interruption</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect4" id="fiber.fiber_mgmt.this_fiber.h0">
|
|
<phrase id="fiber.fiber_mgmt.this_fiber.constructor"/><link linkend="fiber.fiber_mgmt.this_fiber.constructor">Constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">disable_interruption</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Stores the current state of <link linkend="this_fiber_interruption_enabled"> <code>this_fiber::interruption_enabled()</code></link> and
|
|
disables interruption for the current fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="this_fiber_interruption_enabled"> <code>this_fiber::interruption_enabled()</code></link> returns
|
|
<code><phrase role="keyword">false</phrase></code> for the current
|
|
fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect4" id="fiber.fiber_mgmt.this_fiber.h1">
|
|
<phrase id="fiber.fiber_mgmt.this_fiber.destructor"/><link linkend="fiber.fiber_mgmt.this_fiber.destructor">Destructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="special">~</phrase><phrase role="identifier">disable_interruption</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Preconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
Must be called from the same fiber on which <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code> was constructed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Restores the state of <link linkend="this_fiber_interruption_enabled"> <code>this_fiber::interruption_enabled()</code></link> for
|
|
the current fiber to the state saved at construction of <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="this_fiber_interruption_enabled"> <code>this_fiber::interruption_enabled()</code></link> for
|
|
the current fiber returns the value stored by the constructor of <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_restore_interruption_bridgehead">
|
|
<phrase id="class_restore_interruption"/>
|
|
<link linkend="class_restore_interruption">Class
|
|
<code>restore_interruption</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">interruption</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">restore_interruption</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="keyword">explicit</phrase> <phrase role="identifier">restore_interruption</phrase><phrase role="special">(</phrase><phrase role="identifier">disable_interruption</phrase><phrase role="special">&</phrase> <phrase role="identifier">disabler</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">~</phrase><phrase role="identifier">restore_interruption</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">restore_interruption</phrase><phrase role="special">(</phrase><phrase role="keyword">const</phrase> <phrase role="identifier">restore_interruption</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">restore_interruption</phrase><phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase><phrase role="keyword">const</phrase> <phrase role="identifier">restore_interruption</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect4" id="fiber.fiber_mgmt.this_fiber.h2">
|
|
<phrase id="fiber.fiber_mgmt.this_fiber.constructor0"/><link linkend="fiber.fiber_mgmt.this_fiber.constructor0">Constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="keyword">explicit</phrase> <phrase role="identifier">restore_interruption</phrase><phrase role="special">(</phrase><phrase role="identifier">disable_interruption</phrase><phrase role="special">&</phrase> <phrase role="identifier">disabler</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Preconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
Must be called from the same fiber on which <code><phrase role="identifier">disabler</phrase></code>
|
|
was constructed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Restores the current state of <link linkend="this_fiber_interruption_enabled"> <code>this_fiber::interruption_enabled()</code></link> for
|
|
the current fiber to that saved in <code><phrase role="identifier">disabler</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="this_fiber_interruption_enabled"> <code>this_fiber::interruption_enabled()</code></link> for
|
|
the current fiber returns the value stored in the constructor of <code><phrase
|
|
role="identifier">disabler</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect4" id="fiber.fiber_mgmt.this_fiber.h3">
|
|
<phrase id="fiber.fiber_mgmt.this_fiber.destructor0"/><link linkend="fiber.fiber_mgmt.this_fiber.destructor0">Destructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="special">~</phrase><phrase role="identifier">restore_interruption</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Preconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
Must be called from the same fiber on which <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code> was constructed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Disables interruption for the current fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="this_fiber_interruption_enabled"> <code>this_fiber::interruption_enabled()</code></link> for
|
|
the current fiber returns <code><phrase role="keyword">false</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">foo</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="comment">// interruption is enabled</phrase>
|
|
<phrase role="special">{</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">disable_interruption</phrase> <phrase role="identifier">di</phrase><phrase role="special">;</phrase>
|
|
<phrase role="comment">// interruption is disabled</phrase>
|
|
<phrase role="special">{</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">restore_interruption</phrase> <phrase role="identifier">ri</phrase><phrase role="special">(</phrase> <phrase role="identifier">di</phrase><phrase role="special">);</phrase>
|
|
<phrase role="comment">// interruption now enabled</phrase>
|
|
<phrase role="special">}</phrase> <phrase role="comment">// ri destroyed, interruption disable again</phrase>
|
|
<phrase role="special">}</phrase> <phrase role="comment">// di destructed, interruption state restored</phrase>
|
|
<phrase role="comment">// interruption now enabled</phrase>
|
|
<phrase role="special">}</phrase>
|
|
</programlisting>
|
|
</section>
|
|
<section id="fiber.fiber_mgmt.winfibers">
|
|
<title><link linkend="fiber.fiber_mgmt.winfibers">Using WinFiber-API</link></title>
|
|
<para>
|
|
Because the TIB (thread information block) is not fully described in the
|
|
MSDN, it might be possible that not all required TIB-parts are swapped. With
|
|
compiler flag <code><phrase role="identifier">BOOST_USE_WINFIBERS</phrase></code>
|
|
<code><phrase role="identifier">fiber</phrase></code> uses internally the
|
|
Windows Fiber API.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section id="fiber.scheduling">
|
|
<title><anchor id="scheduling"/><link linkend="fiber.scheduling">Scheduling</link></title>
|
|
<para>
|
|
The fibers in a thread are coordinated by a fiber manager. Fibers trade control
|
|
cooperatively, rather than preemptively: the currently-running fiber retains
|
|
control until it invokes some operation that passes control to the manager.
|
|
Each time a fiber suspends (or yields), the fiber manager consults a scheduler
|
|
to determine which fiber will run next.
|
|
</para>
|
|
<para>
|
|
<emphasis role="bold">Boost.Fiber</emphasis> provides the fiber manager, but
|
|
the scheduler is a customization point. (See <link linkend="custom">custom</link>.)
|
|
</para>
|
|
<para>
|
|
Each thread has its own scheduler. By default, <emphasis role="bold">Boost.Fiber</emphasis>
|
|
implicitly instantiates <link linkend="class_round_robin"> <code>round_robin</code></link> as the scheduler for each
|
|
thread.
|
|
</para>
|
|
<para>
|
|
You are explicitly permitted to code your own <link linkend="class_sched_algorithm"> <code>sched_algorithm</code></link> subclass,
|
|
and to pass it to <link linkend="set_scheduling_algorithm"> <code>set_scheduling_algorithm()</code></link>.
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">thread_fn</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="identifier">my_fiber_scheduler</phrase> <phrase role="identifier">mfs</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">set_scheduling_algorithm</phrase><phrase role="special">(</phrase> <phrase role="special">&</phrase> <phrase role="identifier">mfs</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">...</phrase>
|
|
<phrase role="special">}</phrase>
|
|
</programlisting>
|
|
<para>
|
|
A scheduler class must implement interface <link linkend="class_sched_algorithm"> <code>sched_algorithm</code></link>.
|
|
<emphasis role="bold">Boost.Fiber</emphasis> provides one scheduler: <link linkend="class_round_robin"> <code>round_robin</code></link>.
|
|
</para>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_sched_algorithm_bridgehead">
|
|
<phrase id="class_sched_algorithm"/>
|
|
<link linkend="class_sched_algorithm">Class
|
|
<code>sched_algorithm</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<para>
|
|
<code><phrase role="identifier">sched_algorithm</phrase></code> is the abstract
|
|
base class defining the interface that a fiber scheduler must implement.
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">algorithm</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">struct</phrase> <phrase role="identifier">sched_algorithm</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">virtual</phrase> <phrase role="special">~</phrase><phrase role="identifier">sched_algorithm</phrase><phrase role="special">()</phrase> <phrase role="special">{}</phrase>
|
|
|
|
<phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*)</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">virtual</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">virtual</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="sched_algorithm_awakened_bridgehead">
|
|
<phrase id="sched_algorithm_awakened"/>
|
|
<link linkend="sched_algorithm_awakened">Member
|
|
function <code>awakened</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Informs the scheduler that fiber <code><phrase role="identifier">f</phrase></code>
|
|
is ready to run. Fiber <code><phrase role="identifier">f</phrase></code>
|
|
might be newly launched, or it might have been blocked but has just been
|
|
awakened, or it might have called <link linkend="this_fiber_yield"> <code>this_fiber::yield()</code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
This method advises the scheduler to add fiber <code><phrase role="identifier">f</phrase></code>
|
|
to its collection of fibers ready to run. A typical scheduler implementation
|
|
places <code><phrase role="identifier">f</phrase></code> into a queue.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>See also:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="class_round_robin"> <code>round_robin</code></link>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="sched_algorithm_pick_next_bridgehead">
|
|
<phrase id="sched_algorithm_pick_next"/>
|
|
<link linkend="sched_algorithm_pick_next">Member
|
|
function <code>pick_next</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">virtual</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
the fiber which is to be resumed next, or <code><phrase role="keyword">nullptr</phrase></code>
|
|
if there is no ready fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
This is where the scheduler actually specifies the fiber which is to
|
|
run next. A typical scheduler implementation chooses the head of the
|
|
ready queue.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>See also:</term>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="class_round_robin"> <code>round_robin</code></link>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="sched_algorithm_ready_fibers_bridgehead">
|
|
<phrase id="sched_algorithm_ready_fibers"/>
|
|
<link linkend="sched_algorithm_ready_fibers">Member
|
|
function <code>ready_fibers</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">virtual</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Returns 0 if scheduling algorithm has no fibers ready to run, otherwise
|
|
nonzero.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_round_robin_bridgehead">
|
|
<phrase id="class_round_robin"/>
|
|
<link linkend="class_round_robin">Class <code>round_robin</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<para>
|
|
This class implements <link linkend="class_sched_algorithm"> <code>sched_algorithm</code></link>, scheduling fibers
|
|
in round-robin fashion.
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">round_robin</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">round_robin</phrase> <phrase role="special">:</phrase> <phrase role="keyword">public</phrase> <phrase role="identifier">sched_algorithm</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*);</phrase>
|
|
|
|
<phrase role="keyword">virtual</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">virtual</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="round_robin_awakened_bridgehead">
|
|
<phrase id="round_robin_awakened"/>
|
|
<link linkend="round_robin_awakened">Member
|
|
function <code>awakened</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Enqueues fiber <code><phrase role="identifier">f</phrase></code> onto
|
|
a ready queue.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="round_robin_pick_next_bridgehead">
|
|
<phrase id="round_robin_pick_next"/>
|
|
<link linkend="round_robin_pick_next">Member
|
|
function <code>pick_next</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">virtual</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
the fiber at the head of the ready queue, or 0 if the queue is empty.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
Placing ready fibers onto a queue, and returning them from the head of
|
|
that queue, shares the thread between ready fibers in round-robin fashion.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="round_robin_ready_fibers_bridgehead">
|
|
<phrase id="round_robin_ready_fibers"/>
|
|
<link linkend="round_robin_ready_fibers">Member
|
|
function <code>ready_fibers</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">virtual</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
0 if scheduling algorithm has no fibers ready to run, otherwise nonzero.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect3" id="fiber.scheduling.h0">
|
|
<phrase id="fiber.scheduling.custom_scheduler_fiber_properties"/><link linkend="fiber.scheduling.custom_scheduler_fiber_properties">Custom
|
|
Scheduler Fiber Properties</link>
|
|
</bridgehead>
|
|
<para>
|
|
A scheduler class directly derived from <link linkend="class_sched_algorithm"> <code>sched_algorithm</code></link> can
|
|
use any information available from <link linkend="class_fiber_context"> <code>fiber_context</code></link> to implement
|
|
the <code><phrase role="identifier">sched_algorithm</phrase></code> interface.
|
|
But a custom scheduler might need to track additional properties for a fiber.
|
|
For instance, a priority-based scheduler would need to track a fiber's priority.
|
|
</para>
|
|
<para>
|
|
<emphasis role="bold">Boost.Fiber</emphasis> provides a mechanism by which
|
|
your custom scheduler can associate custom properties with each fiber.
|
|
</para>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_fiber_properties_bridgehead">
|
|
<phrase id="class_fiber_properties"/>
|
|
<link linkend="class_fiber_properties">Class
|
|
<code>fiber_properties</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<para>
|
|
A custom fiber properties class must be derived from <code><phrase role="identifier">fiber_properties</phrase></code>.
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">properties</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">fiber_properties</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">fiber_properties</phrase><phrase role="special">(</phrase> <phrase role="identifier">back_ptr</phrase> <phrase role="identifier">f</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">virtual</phrase> <phrase role="special">~</phrase><phrase role="identifier">fiber_properties</phrase><phrase role="special">()</phrase> <phrase role="special">{}</phrase>
|
|
|
|
<phrase role="keyword">protected</phrase><phrase role="special">:</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect3" id="fiber.scheduling.h1">
|
|
<phrase id="fiber.scheduling.constructor"/><link linkend="fiber.scheduling.constructor">Constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">fiber_properties</phrase><phrase role="special">(</phrase> <phrase role="identifier">back_ptr</phrase> <phrase role="identifier">f</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Constructs base-class component of custom subclass.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
Your subclass constructor must accept a <code><phrase role="identifier">back_ptr</phrase></code>
|
|
and pass it to the base-class <code><phrase role="identifier">fiber_properties</phrase></code>
|
|
constructor.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_properties_notify_bridgehead">
|
|
<phrase id="fiber_properties_notify"/>
|
|
<link linkend="fiber_properties_notify">Member
|
|
function <code>notify</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Pass control to the custom <link linkend="class_sched_algorithm_with_properties"> <code>sched_algorithm_with_properties<></code></link> subclass's
|
|
<link linkend="sched_algorithm_with_properties_property_change"> <code>sched_algorithm_with_properties::property_change()</code></link> method.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
A custom scheduler's <link linkend="sched_algorithm_with_properties_pick_next"> <code>sched_algorithm_with_properties::pick_next()</code></link> method
|
|
might dynamically select from the ready fibers, or <link linkend="sched_algorithm_with_properties_awakened"> <code>sched_algorithm_with_properties::awakened()</code></link> might
|
|
instead insert each ready fiber into some form of ready queue for <code><phrase
|
|
role="identifier">pick_next</phrase><phrase role="special">()</phrase></code>.
|
|
In the latter case, if application code modifies a fiber property (e.g.
|
|
priority) that should affect that fiber's relationship to other ready
|
|
fibers, the custom scheduler must be given the opportunity to reorder
|
|
its ready queue. The custom property subclass should implement an access
|
|
method to modify such a property; that access method should call <code><phrase
|
|
role="identifier">notify</phrase><phrase role="special">()</phrase></code>
|
|
once the new property value has been stored. This passes control to the
|
|
custom scheduler's <code><phrase role="identifier">property_change</phrase><phrase
|
|
role="special">()</phrase></code> method, allowing the custom scheduler
|
|
to reorder its ready queue appropriately. Use at your discretion. Of
|
|
course, if you define a property which does not affect the behavior of
|
|
the <code><phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase></code>
|
|
method, you need not call <code><phrase role="identifier">notify</phrase><phrase
|
|
role="special">()</phrase></code> when that property is modified.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_sched_algorithm_with_properties_bridgehead">
|
|
<phrase id="class_sched_algorithm_with_properties"/>
|
|
<link linkend="class_sched_algorithm_with_properties">Template
|
|
<code>sched_algorithm_with_properties<></code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<para>
|
|
A custom scheduler that depends on a custom properties class <code><phrase
|
|
role="identifier">PROPS</phrase></code> should be derived from <code><phrase
|
|
role="identifier">sched_algorithm_with_properties</phrase><phrase role="special"><</phrase><phrase
|
|
role="identifier">PROPS</phrase><phrase role="special">></phrase></code>.
|
|
<code><phrase role="identifier">PROPS</phrase></code> should be derived from
|
|
<link linkend="class_fiber_properties"> <code>fiber_properties</code></link>.
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">algorithm</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">struct</phrase> <phrase role="identifier">sched_algorithm_with_properties</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="comment">// override this method instead of sched_algorithm::awakened()</phrase>
|
|
<phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">,</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">virtual</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">virtual</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="comment">// obtain f's associated PROPS instance</phrase>
|
|
<phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="comment">// override this to be notified by PROPS::notify()</phrase>
|
|
<phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">property_change</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">,</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="comment">// Override this to customize instantiation of PROPS, e.g. use a different</phrase>
|
|
<phrase role="comment">// allocator. Each PROPS instance is associated with a particular</phrase>
|
|
<phrase role="comment">// fiber_context.</phrase>
|
|
<phrase role="keyword">virtual</phrase> <phrase role="identifier">fiber_properties</phrase> <phrase role="special">*</phrase> <phrase role="identifier">new_properties</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="sched_algorithm_with_properties_awakened_bridgehead">
|
|
<phrase id="sched_algorithm_with_properties_awakened"/>
|
|
<link linkend="sched_algorithm_with_properties_awakened">Member
|
|
function <code>awakened</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">,</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Informs the scheduler that fiber <code><phrase role="identifier">f</phrase></code>
|
|
is ready to run, like <link linkend="sched_algorithm_awakened"> <code>sched_algorithm::awakened()</code></link>.
|
|
Passes the fiber's associated <code><phrase role="identifier">PROPS</phrase></code>
|
|
instance.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
A <code><phrase role="identifier">sched_algorithm_with_properties</phrase><phrase
|
|
role="special"><></phrase></code> subclass must override this method
|
|
instead of <code><phrase role="identifier">sched_algorithm</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">awakened</phrase><phrase
|
|
role="special">()</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="sched_algorithm_with_properties_pick_next_bridgehead">
|
|
<phrase id="sched_algorithm_with_properties_pick_next"/>
|
|
<link linkend="sched_algorithm_with_properties_pick_next">Member
|
|
function <code>pick_next</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">virtual</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
the fiber which is to be resumed next, or <code><phrase role="keyword">nullptr</phrase></code>
|
|
if there is no ready fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
same as <link linkend="sched_algorithm_pick_next"> <code>sched_algorithm::pick_next()</code></link>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="sched_algorithm_with_properties_ready_fibers_bridgehead">
|
|
<phrase id="sched_algorithm_with_properties_ready_fibers"/>
|
|
<link linkend="sched_algorithm_with_properties_ready_fibers">Member
|
|
function <code>ready_fibers</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">virtual</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
0 if scheduling algorithm has no fibers ready to run, otherwise nonzero.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
same as <link linkend="sched_algorithm_ready_fibers"> <code>sched_algorithm::ready_fibers()</code></link>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="sched_algorithm_with_properties_properties_bridgehead">
|
|
<phrase id="sched_algorithm_with_properties_properties"/>
|
|
<link linkend="sched_algorithm_with_properties_properties">Member
|
|
function <code>properties</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">PROPS</phrase><phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
the <code><phrase role="identifier">PROPS</phrase></code> instance associated
|
|
with fiber <code><phrase role="identifier">f</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
The fiber's associated <code><phrase role="identifier">PROPS</phrase></code>
|
|
instance is already passed to <code><phrase role="identifier">awakened</phrase><phrase
|
|
role="special">()</phrase></code> and <code><phrase role="identifier">property_change</phrase><phrase
|
|
role="special">()</phrase></code>. However, every <link linkend="class_sched_algorithm"> <code>sched_algorithm</code></link> subclass
|
|
is expected to track a collection of ready <link linkend="class_fiber_context"> <code>fiber_context</code></link> instances.
|
|
This method allows your custom scheduler to retrieve the <link linkend="class_fiber_properties"> <code>fiber_properties</code></link> subclass
|
|
instance for any <code><phrase role="identifier">fiber_context</phrase></code>
|
|
in its collection.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="sched_algorithm_with_properties_property_change_bridgehead">
|
|
<phrase id="sched_algorithm_with_properties_property_change"/>
|
|
<link linkend="sched_algorithm_with_properties_property_change">Member
|
|
function <code>property_change</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">property_change</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">,</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Notify the custom scheduler of a possibly-relevant change to a property
|
|
belonging to fiber <code><phrase role="identifier">f</phrase></code>.
|
|
<code><phrase role="identifier">properties</phrase></code> contains the
|
|
new values of all relevant properties.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
This method is only called when a custom <link linkend="class_fiber_properties"> <code>fiber_properties</code></link> subclass
|
|
explicitly calls <link linkend="fiber_properties_notify"> <code>fiber_properties::notify()</code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="sched_algorithm_with_properties_new_properties_bridgehead">
|
|
<phrase id="sched_algorithm_with_properties_new_properties"/>
|
|
<link linkend="sched_algorithm_with_properties_new_properties">Member
|
|
function <code>new_properties</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">virtual</phrase> <phrase role="identifier">fiber_properties</phrase> <phrase role="special">*</phrase> <phrase role="identifier">new_properties</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
A new instance of <link linkend="class_fiber_properties"> <code>fiber_properties</code></link> subclass <code><phrase
|
|
role="identifier">PROPS</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
By default, <code><phrase role="identifier">sched_algorithm_with_properties</phrase><phrase
|
|
role="special"><>::</phrase><phrase role="identifier">new_properties</phrase><phrase
|
|
role="special">()</phrase></code> simply returns <code><phrase role="keyword">new</phrase>
|
|
<phrase role="identifier">PROPS</phrase><phrase role="special">(</phrase><phrase
|
|
role="identifier">f</phrase><phrase role="special">)</phrase></code>,
|
|
placing the <code><phrase role="identifier">PROPS</phrase></code> instance
|
|
on the heap. Override this method to allocate <code><phrase role="identifier">PROPS</phrase></code>
|
|
some other way. The returned <code><phrase role="identifier">fiber_properties</phrase></code>
|
|
pointer must point to the <code><phrase role="identifier">PROPS</phrase></code>
|
|
instance to be associated with fiber <code><phrase role="identifier">f</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_fiber_context_bridgehead">
|
|
<phrase id="class_fiber_context"/>
|
|
<link linkend="class_fiber_context">Class <code>fiber_context</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<para>
|
|
While you are free to treat <code><phrase role="identifier">fiber_context</phrase><phrase
|
|
role="special">*</phrase></code> as an opaque token, certain <code><phrase
|
|
role="identifier">fiber_context</phrase></code> members may be useful to a
|
|
custom scheduler implementation.
|
|
</para>
|
|
<para>
|
|
(Most <code><phrase role="identifier">fiber_context</phrase></code> members
|
|
are implementation details; most of interest are implementations of <link linkend="class_fiber"> <code>fiber</code></link> methods.)
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber_context</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">nxt</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">static</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">main_fiber</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_context_nxt_bridgehead">
|
|
<phrase id="fiber_context_nxt"/>
|
|
<link linkend="fiber_context_nxt">Data member <code>nxt</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">nxt</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
This link pointer may be used to help implement a custom scheduler's
|
|
ready queue. It is overwritten by the fiber manager every time this
|
|
<code><phrase role="identifier">fiber_context</phrase></code> is returned
|
|
by <link linkend="sched_algorithm_pick_next"> <code>sched_algorithm::pick_next()</code></link>, but between
|
|
the time the fiber manager passes this <code><phrase role="identifier">fiber_context</phrase></code>
|
|
to <link linkend="sched_algorithm_awakened"> <code>sched_algorithm::awakened()</code></link> (or <link linkend="sched_algorithm_with_properties_awakened"> <code>sched_algorithm_with_properties::awakened()</code></link>)
|
|
and the time your <code><phrase role="identifier">pick_next</phrase><phrase
|
|
role="special">()</phrase></code> returns it to the fiber manager, it
|
|
is available for use by your custom scheduler.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_context_main_fiber_bridgehead">
|
|
<phrase id="fiber_context_main_fiber"/>
|
|
<link linkend="fiber_context_main_fiber">Static
|
|
member function <code>main_fiber</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">static</phrase> <phrase role="identifier">fiber_context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">main_fiber</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
the <code><phrase role="identifier">fiber_context</phrase></code> associated
|
|
with the "main" fiber of the thread: the one implicitly created
|
|
by the thread itself, rather than one explicitly created by <emphasis
|
|
role="bold">Boost.Fiber</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
<section id="fiber.stack">
|
|
<title><anchor id="stack"/><link linkend="fiber.stack">Stack allocation</link></title>
|
|
<para>
|
|
A <link linkend="class_fiber"> <code>fiber</code></link> uses internally a <ulink url="boost:/libs/context/doc/html/context/econtext.html"><emphasis>execution_context</emphasis></ulink>
|
|
which manages a set of registers and a stack. The memory used by the stack
|
|
is allocated/deallocated via a <emphasis>stack_allocator</emphasis> which is
|
|
required to model a <link linkend="stack_allocator_concept"><emphasis>stack-allocator
|
|
concept</emphasis></link>.
|
|
</para>
|
|
<anchor id="stack_allocator_concept"/>
|
|
<bridgehead renderas="sect3" id="fiber.stack.h0">
|
|
<phrase id="fiber.stack._link_linkend__stack_allocator_concept___emphasis_stack_allocator_concept__emphasis___link_"/><link
|
|
linkend="fiber.stack._link_linkend__stack_allocator_concept___emphasis_stack_allocator_concept__emphasis___link_"><link
|
|
linkend="stack_allocator_concept"><emphasis>stack-allocator concept</emphasis></link></link>
|
|
</bridgehead>
|
|
<para>
|
|
A <emphasis>stack_allocator</emphasis> must satisfy the <link linkend="stack_allocator_concept"><emphasis>stack-allocator
|
|
concept</emphasis></link> requirements shown in the following table, in which
|
|
<code><phrase role="identifier">a</phrase></code> is an object of a <emphasis>stack_allocator</emphasis>
|
|
type, <code><phrase role="identifier">sctx</phrase></code> is a <ulink url="boost:/libs/context/doc/html/context/stack/stack_context.html"><code><phrase
|
|
role="identifier">stack_context</phrase></code></ulink>, and <code><phrase
|
|
role="identifier">size</phrase></code> is a <code><phrase role="identifier">std</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">size_t</phrase></code>:
|
|
</para>
|
|
<informaltable frame="all">
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
expression
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
return type
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
notes
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<code><phrase role="identifier">a</phrase><phrase role="special">(</phrase><phrase
|
|
role="identifier">size</phrase><phrase role="special">)</phrase></code>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
creates a stack allocator
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<code><phrase role="identifier">a</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">allocate</phrase><phrase role="special">()</phrase></code>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<ulink url="boost:/libs/context/doc/html/context/stack/stack_context.html"><code><phrase
|
|
role="identifier">stack_context</phrase></code></ulink>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
creates a stack
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<code><phrase role="identifier">a</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">deallocate</phrase><phrase role="special">(</phrase>
|
|
<phrase role="identifier">sctx</phrase><phrase role="special">)</phrase></code>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<code><phrase role="keyword">void</phrase></code>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
deallocates the stack created by <code><phrase role="identifier">a</phrase><phrase
|
|
role="special">.</phrase><phrase role="identifier">allocate</phrase><phrase
|
|
role="special">()</phrase></code>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<important>
|
|
<para>
|
|
The implementation of <code><phrase role="identifier">allocate</phrase><phrase
|
|
role="special">()</phrase></code> might include logic to protect against
|
|
exceeding the context's available stack size rather than leaving it as undefined
|
|
behaviour.
|
|
</para>
|
|
</important>
|
|
<important>
|
|
<para>
|
|
Calling <code><phrase role="identifier">deallocate</phrase><phrase role="special">()</phrase></code>
|
|
with a <ulink url="boost:/libs/context/doc/html/context/stack/stack_context.html"><code><phrase
|
|
role="identifier">stack_context</phrase></code></ulink> not obtained from
|
|
<code><phrase role="identifier">allocate</phrase><phrase role="special">()</phrase></code>
|
|
results in undefined behaviour.
|
|
</para>
|
|
</important>
|
|
<note>
|
|
<para>
|
|
The memory for the stack is not required to be aligned; alignment takes place
|
|
inside <ulink url="boost:/libs/context/doc/html/context/econtext.html"><emphasis>execution_context</emphasis></ulink>.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
See also <ulink url="boost:/libs/context/doc/html/context/stack.html">Boost.Context
|
|
stack allocation</ulink>.
|
|
</para>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_protected_fixedsize_stack_bridgehead">
|
|
<phrase id="class_protected_fixedsize_stack"/>
|
|
<link linkend="class_protected_fixedsize_stack">Class
|
|
<code>protected_fixedsize_stack</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<para>
|
|
<emphasis role="bold">Boost.Fiber</emphasis> provides the class <link linkend="class_protected_fixedsize_stack"> <code>protected_fixedsize_stack</code></link> which
|
|
models the <link linkend="stack_allocator_concept"><emphasis>stack-allocator
|
|
concept</emphasis></link>. It appends a guard page at the end of each stack
|
|
to protect against exceeding the stack. If the guard page is accessed (read
|
|
or write operation) a segmentation fault/access violation is generated by the
|
|
operating system.
|
|
</para>
|
|
<important>
|
|
<para>
|
|
Using <link linkend="class_protected_fixedsize_stack"> <code>protected_fixedsize_stack</code></link> is expensive.
|
|
Launching a new fiber with a stack of this type incurs the overhead of setting
|
|
the memory protection; once allocated, this stack is just as efficient to
|
|
use as <link linkend="class_fixedsize_stack"> <code>fixedsize_stack</code></link>.
|
|
</para>
|
|
</important>
|
|
<note>
|
|
<para>
|
|
The appended <code><phrase role="identifier">guard</phrase> <phrase role="identifier">page</phrase></code>
|
|
is <emphasis role="bold">not</emphasis> mapped to physical memory, only virtual
|
|
addresses are used.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_fixedsize_stack_bridgehead">
|
|
<phrase id="class_fixedsize_stack"/>
|
|
<link linkend="class_fixedsize_stack">Class
|
|
<code>fixedsize_stack</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<para>
|
|
<emphasis role="bold">Boost.Fiber</emphasis> provides the class <link linkend="class_fixedsize_stack"> <code>fixedsize_stack</code></link> which
|
|
models the <link linkend="stack_allocator_concept"><emphasis>stack-allocator
|
|
concept</emphasis></link>. In contrast to <link linkend="class_protected_fixedsize_stack"> <code>protected_fixedsize_stack</code></link> it
|
|
does not append a guard page at the end of each stack. The memory is simply
|
|
managed by <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">malloc</phrase><phrase role="special">()</phrase></code>
|
|
and <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">free</phrase><phrase role="special">()</phrase></code>.
|
|
</para>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_segmented_stack_bridgehead">
|
|
<phrase id="class_segmented_stack"/>
|
|
<link linkend="class_segmented_stack">Class
|
|
<code>segmented_stack</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<para>
|
|
<emphasis role="bold">Boost.Fiber</emphasis> supports usage of a <link linkend="class_segmented_stack"> <code>segmented_stack</code></link>,
|
|
i.e. the stack grows on demand. The fiber is created with a minimal stack size
|
|
which will be increased as required. Class <link linkend="class_segmented_stack"> <code>segmented_stack</code></link> models
|
|
the <link linkend="stack_allocator_concept"><emphasis>stack-allocator concept</emphasis></link>.
|
|
In contrast to <link linkend="class_protected_fixedsize_stack"> <code>protected_fixedsize_stack</code></link> and
|
|
<link linkend="class_fixedsize_stack"> <code>fixedsize_stack</code></link> it creates a stack which grows on demand.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Segmented stacks are currently only supported by <emphasis role="bold">gcc</emphasis>
|
|
from version <emphasis role="bold">4.7</emphasis> and <emphasis role="bold">clang</emphasis>
|
|
from version <emphasis role="bold">3.4</emphasis> onwards. In order to use
|
|
a <link linkend="class_segmented_stack"> <code>segmented_stack</code></link>, <emphasis role="bold">Boost.Fiber</emphasis>
|
|
must be built with property <code><phrase role="identifier">segmented</phrase><phrase
|
|
role="special">-</phrase><phrase role="identifier">stacks</phrase></code>,
|
|
e.g. <emphasis role="bold">toolset=gcc segmented-stacks=on</emphasis> at
|
|
b2/bjam command line.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
<section id="fiber.synchronization">
|
|
<title><anchor id="synchronization"/><link linkend="fiber.synchronization">Synchronization</link></title>
|
|
<para>
|
|
In general, <emphasis role="bold">Boost.Fiber</emphasis> 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 <emphasis>moved</emphasis>
|
|
somewhere else, leaving the original instance in an unspecified state, existing
|
|
consumers would behave strangely.
|
|
</para>
|
|
<para>
|
|
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 <code><phrase role="identifier">BOOST_FIBERS_NO_ATOMICS</phrase></code>
|
|
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.
|
|
</para>
|
|
<section id="fiber.synchronization.mutex_types">
|
|
<title><link linkend="fiber.synchronization.mutex_types">Mutex Types</link></title>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_mutex_bridgehead">
|
|
<phrase id="class_mutex"/>
|
|
<link linkend="class_mutex">Class <code>mutex</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">mutex</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">mutex</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">mutex</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">~</phrase><phrase role="identifier">mutex</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">mutex</phrase><phrase role="special">(</phrase> <phrase role="identifier">mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">mutex</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">();</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<para>
|
|
<link linkend="class_mutex"> <code>mutex</code></link> provides an exclusive-ownership mutex. At most one fiber
|
|
can own the lock on a given instance of <link linkend="class_mutex"> <code>mutex</code></link> at any time. Multiple
|
|
concurrent calls to <code><phrase role="identifier">lock</phrase><phrase
|
|
role="special">()</phrase></code>, <code><phrase role="identifier">try_lock</phrase><phrase
|
|
role="special">()</phrase></code> and <code><phrase role="identifier">unlock</phrase><phrase
|
|
role="special">()</phrase></code> shall be permitted.
|
|
</para>
|
|
<para>
|
|
Any fiber blocked in <code><phrase role="identifier">lock</phrase><phrase
|
|
role="special">()</phrase></code> is suspended in the scheduler until the
|
|
owning fiber releases the lock by calling <code><phrase role="identifier">unlock</phrase><phrase
|
|
role="special">()</phrase></code>.
|
|
</para>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="mutex_lock_bridgehead">
|
|
<phrase id="mutex_lock"/>
|
|
<link linkend="mutex_lock">Member function <code>lock</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
The calling fiber doesn't own the mutex.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
The current fiber blocks until ownership can be obtained.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="mutex_try_lock_bridgehead">
|
|
<phrase id="mutex_try_lock"/>
|
|
<link linkend="mutex_try_lock">Member function <code>try_lock</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
The calling fiber doesn't own the mutex.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Attempt to obtain ownership for the current fiber without blocking.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if ownership was
|
|
obtained for the current fiber, <code><phrase role="keyword">false</phrase></code>
|
|
otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="mutex_unlock_bridgehead">
|
|
<phrase id="mutex_unlock"/>
|
|
<link linkend="mutex_unlock">Member function <code>unlock</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
The current fiber owns <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Releases a lock on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
by the current fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_timed_mutex_bridgehead">
|
|
<phrase id="class_timed_mutex"/>
|
|
<link linkend="class_timed_mutex">Class <code>timed_mutex</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">timed_mutex</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">timed_mutex</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">timed_mutex</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">~</phrase><phrase role="identifier">timed_mutex</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">timed_mutex</phrase><phrase role="special">(</phrase> <phrase role="identifier">timed_mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">timed_mutex</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">timed_mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<para>
|
|
<link linkend="class_timed_mutex"> <code>timed_mutex</code></link> provides an exclusive-ownership mutex. At most
|
|
one fiber can own the lock on a given instance of <link linkend="class_timed_mutex"> <code>timed_mutex</code></link> at
|
|
any time. Multiple concurrent calls to <code><phrase role="identifier">lock</phrase><phrase
|
|
role="special">()</phrase></code>, <code><phrase role="identifier">try_lock</phrase><phrase
|
|
role="special">()</phrase></code>, <code><phrase role="identifier">try_lock_until</phrase><phrase
|
|
role="special">()</phrase></code>, <code><phrase role="identifier">try_lock_for</phrase><phrase
|
|
role="special">()</phrase></code> and <code><phrase role="identifier">unlock</phrase><phrase
|
|
role="special">()</phrase></code> shall be permitted.
|
|
</para>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="timed_mutex_lock_bridgehead">
|
|
<phrase id="timed_mutex_lock"/>
|
|
<link linkend="timed_mutex_lock">Member function
|
|
<code>lock</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
The calling fiber doesn't own the mutex.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
The current fiber blocks until ownership can be obtained.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="timed_mutex_try_lock_bridgehead">
|
|
<phrase id="timed_mutex_try_lock"/>
|
|
<link linkend="timed_mutex_try_lock">Member
|
|
function <code>try_lock</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
The calling fiber doesn't own the mutex.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Attempt to obtain ownership for the current fiber without blocking.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if ownership was
|
|
obtained for the current fiber, <code><phrase role="keyword">false</phrase></code>
|
|
otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="timed_mutex_unlock_bridgehead">
|
|
<phrase id="timed_mutex_unlock"/>
|
|
<link linkend="timed_mutex_unlock">Member function
|
|
<code>unlock</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
The current fiber owns <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Releases a lock on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
by the current fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="timed_mutex_try_lock_until_bridgehead">
|
|
<phrase id="timed_mutex_try_lock_until"/>
|
|
<link linkend="timed_mutex_try_lock_until">Templated
|
|
member function <code>try_lock_until</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
The calling fiber doesn't own the mutex.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Attempt to obtain ownership for the current fiber. Blocks until ownership
|
|
can be obtained, or the specified time is reached. If the specified
|
|
time has already passed, behaves as <link linkend="timed_mutex_try_lock"> <code>timed_mutex::try_lock()</code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if ownership was
|
|
obtained for the current fiber, <code><phrase role="keyword">false</phrase></code>
|
|
otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="timed_mutex_try_lock_for_bridgehead">
|
|
<phrase id="timed_mutex_try_lock_for"/>
|
|
<link linkend="timed_mutex_try_lock_for">Templated
|
|
member function <code>try_lock_for</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
The calling fiber doesn't own the mutex.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Attempt to obtain ownership for the current fiber. Blocks until ownership
|
|
can be obtained, or the specified time is reached. If the specified
|
|
time has already passed, behaves as <link linkend="timed_mutex_try_lock"> <code>timed_mutex::try_lock()</code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if ownership was
|
|
obtained for the current fiber, <code><phrase role="keyword">false</phrase></code>
|
|
otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_recursive_mutex_bridgehead">
|
|
<phrase id="class_recursive_mutex"/>
|
|
<link linkend="class_recursive_mutex">Class
|
|
<code>recursive_mutex</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">recursive_mutex</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">recursive_mutex</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">recursive_mutex</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">~</phrase><phrase role="identifier">recursive_mutex</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">recursive_mutex</phrase><phrase role="special">(</phrase> <phrase role="identifier">recursive_mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">recursive_mutex</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">recursive_mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<para>
|
|
<link linkend="class_recursive_mutex"> <code>recursive_mutex</code></link> provides an exclusive-ownership recursive
|
|
mutex. At most one fiber can own the lock on a given instance of <link linkend="class_recursive_mutex"> <code>recursive_mutex</code></link> at
|
|
any time. Multiple concurrent calls to <code><phrase role="identifier">lock</phrase><phrase
|
|
role="special">()</phrase></code>, <code><phrase role="identifier">try_lock</phrase><phrase
|
|
role="special">()</phrase></code> and <code><phrase role="identifier">unlock</phrase><phrase
|
|
role="special">()</phrase></code> shall be permitted. A fiber that already
|
|
has exclusive ownership of a given <link linkend="class_recursive_mutex"> <code>recursive_mutex</code></link> instance
|
|
can call <code><phrase role="identifier">lock</phrase><phrase role="special">()</phrase></code>
|
|
or <code><phrase role="identifier">try_lock</phrase><phrase role="special">()</phrase></code>
|
|
to acquire an additional level of ownership of the mutex. <code><phrase role="identifier">unlock</phrase><phrase
|
|
role="special">()</phrase></code> must be called once for each level of ownership
|
|
acquired by a single fiber before ownership can be acquired by another fiber.
|
|
</para>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="recursive_mutex_lock_bridgehead">
|
|
<phrase id="recursive_mutex_lock"/>
|
|
<link linkend="recursive_mutex_lock">Member
|
|
function <code>lock</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
The current fiber blocks until ownership can be obtained.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="recursive_mutex_try_lock_bridgehead">
|
|
<phrase id="recursive_mutex_try_lock"/>
|
|
<link linkend="recursive_mutex_try_lock">Member
|
|
function <code>try_lock</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Attempt to obtain ownership for the current fiber without blocking.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if ownership was
|
|
obtained for the current fiber, <code><phrase role="keyword">false</phrase></code>
|
|
otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="recursive_mutex_unlock_bridgehead">
|
|
<phrase id="recursive_mutex_unlock"/>
|
|
<link linkend="recursive_mutex_unlock">Member
|
|
function <code>unlock</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Releases a lock on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
by the current fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_recursive_timed_mutex_bridgehead">
|
|
<phrase id="class_recursive_timed_mutex"/>
|
|
<link linkend="class_recursive_timed_mutex">Class
|
|
<code>recursive_timed_mutex</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">recursive_timed_mutex</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">recursive_timed_mutex</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">recursive_timed_mutex</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">~</phrase><phrase role="identifier">recursive_timed_mutex</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">recursive_timed_mutex</phrase><phrase role="special">(</phrase> <phrase role="identifier">recursive_timed_mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">recursive_timed_mutex</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">recursive_timed_mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<para>
|
|
<link linkend="class_recursive_timed_mutex"> <code>recursive_timed_mutex</code></link> provides an exclusive-ownership
|
|
recursive mutex. At most one fiber can own the lock on a given instance of
|
|
<link linkend="class_recursive_timed_mutex"> <code>recursive_timed_mutex</code></link> at any time. Multiple concurrent
|
|
calls to <code><phrase role="identifier">lock</phrase><phrase role="special">()</phrase></code>,
|
|
<code><phrase role="identifier">try_lock</phrase><phrase role="special">()</phrase></code>,
|
|
<code><phrase role="identifier">try_lock_for</phrase><phrase role="special">()</phrase></code>,
|
|
<code><phrase role="identifier">try_lock_until</phrase><phrase role="special">()</phrase></code>
|
|
and <code><phrase role="identifier">unlock</phrase><phrase role="special">()</phrase></code>
|
|
shall be permitted. A fiber that already has exclusive ownership of a given
|
|
<link linkend="class_recursive_timed_mutex"> <code>recursive_timed_mutex</code></link> instance can call <code><phrase
|
|
role="identifier">lock</phrase><phrase role="special">()</phrase></code>,
|
|
<code><phrase role="identifier">try_lock</phrase><phrase role="special">()</phrase></code>,
|
|
<code><phrase role="identifier">try_lock_for</phrase><phrase role="special">()</phrase></code>
|
|
or <code><phrase role="identifier">try_lock_until</phrase><phrase role="special">()</phrase></code>
|
|
to acquire an additional level of ownership of the mutex. <code><phrase role="identifier">unlock</phrase><phrase
|
|
role="special">()</phrase></code> must be called once for each level of ownership
|
|
acquired by a single fiber before ownership can be acquired by another fiber.
|
|
</para>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="recursive_timed_mutex_lock_bridgehead">
|
|
<phrase id="recursive_timed_mutex_lock"/>
|
|
<link linkend="recursive_timed_mutex_lock">Member
|
|
function <code>lock</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
The current fiber blocks until ownership can be obtained.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="recursive_timed_mutex_try_lock_bridgehead">
|
|
<phrase id="recursive_timed_mutex_try_lock"/>
|
|
<link linkend="recursive_timed_mutex_try_lock">Member
|
|
function <code>try_lock</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Attempt to obtain ownership for the current fiber without blocking.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if ownership was
|
|
obtained for the current fiber, <code><phrase role="keyword">false</phrase></code>
|
|
otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="recursive_timed_mutex_unlock_bridgehead">
|
|
<phrase id="recursive_timed_mutex_unlock"/>
|
|
<link linkend="recursive_timed_mutex_unlock">Member
|
|
function <code>unlock</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Releases a lock on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
by the current fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="recursive_timed_mutex_try_lock_until_bridgehead">
|
|
<phrase id="recursive_timed_mutex_try_lock_until"/>
|
|
<link linkend="recursive_timed_mutex_try_lock_until">Templated
|
|
member function <code>try_lock_until</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Attempt to obtain ownership for the current fiber. Blocks until ownership
|
|
can be obtained, or the specified time is reached. If the specified
|
|
time has already passed, behaves as <link linkend="recursive_timed_mutex_try_lock"> <code>recursive_timed_mutex::try_lock()</code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if ownership was
|
|
obtained for the current fiber, <code><phrase role="keyword">false</phrase></code>
|
|
otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="recursive_timed_mutex_try_lock_for_bridgehead">
|
|
<phrase id="recursive_timed_mutex_try_lock_for"/>
|
|
<link linkend="recursive_timed_mutex_try_lock_for">Templated
|
|
member function <code>try_lock_for</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Attempt to obtain ownership for the current fiber. Blocks until ownership
|
|
can be obtained, or the specified time is reached. If the specified
|
|
time has already passed, behaves as <link linkend="recursive_timed_mutex_try_lock"> <code>recursive_timed_mutex::try_lock()</code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> if ownership was
|
|
obtained for the current fiber, <code><phrase role="keyword">false</phrase></code>
|
|
otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
<section id="fiber.synchronization.conditions">
|
|
<title><link linkend="fiber.synchronization.conditions">Condition Variables</link></title>
|
|
<bridgehead renderas="sect4" id="fiber.synchronization.conditions.h0">
|
|
<phrase id="fiber.synchronization.conditions.synopsis"/><link linkend="fiber.synchronization.conditions.synopsis">Synopsis</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="keyword">enum</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">cv_status</phrase><phrase role="special">;</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="identifier">no_timeout</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">timeout</phrase>
|
|
<phrase role="special">};</phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">condition_variable</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">condition_variable_any</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<para>
|
|
The class <code><phrase role="identifier">condition_variable</phrase></code>
|
|
provides a mechanism for a fiber to wait for notification on <code><phrase
|
|
role="identifier">condition_variable</phrase></code>. When the fiber awakens
|
|
from the wait, then it checks to see if the appropriate condition is now
|
|
true, and continues if so. If the condition is not true, then the fiber calls
|
|
<code><phrase role="identifier">wait</phrase></code> again to resume waiting.
|
|
In the simplest case, this condition is just a boolean variable:
|
|
</para>
|
|
<programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">condition_variable</phrase> <phrase role="identifier">cond</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="identifier">mtx</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">data_ready</phrase> <phrase role="special">=</phrase> <phrase role="keyword">false</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">process_data</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">wait_for_data_to_process</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="special">{</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">lock_guard</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="special">></phrase> <phrase role="identifier">lk</phrase><phrase role="special">(</phrase> <phrase role="identifier">mtx</phrase><phrase role="special">);</phrase>
|
|
<phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">data_ready</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="identifier">cond</phrase><phrase role="special">.</phrase><phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">}</phrase>
|
|
<phrase role="special">}</phrase> <phrase role="comment">// release lk</phrase>
|
|
<phrase role="identifier">process_data</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">}</phrase>
|
|
</programlisting>
|
|
<para>
|
|
Notice that the <code><phrase role="identifier">lk</phrase></code> is passed
|
|
to <code><phrase role="identifier">wait</phrase></code>: <code><phrase role="identifier">wait</phrase></code>
|
|
will atomically add the fiber to the set of fibers waiting on the condition
|
|
variable, and unlock the mutex. When the fiber is awakened, the mutex will
|
|
be locked again before the call to <code><phrase role="identifier">wait</phrase></code>
|
|
returns. This allows other fibers to acquire the mutex in order to update
|
|
the shared data, and ensures that the data associated with the condition
|
|
is correctly synchronized.
|
|
</para>
|
|
<para>
|
|
In the meantime, another fiber sets <code><phrase role="identifier">data_ready</phrase></code>
|
|
to <code><phrase role="keyword">true</phrase></code>, and then calls either
|
|
<code><phrase role="identifier">notify_one</phrase></code> or <code><phrase
|
|
role="identifier">notify_all</phrase></code> on the condition variable <code><phrase
|
|
role="identifier">cond</phrase></code> to wake one waiting fiber or all the
|
|
waiting fibers respectively.
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">retrieve_data</phrase><phrase role="special">();</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">prepare_data</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">prepare_data_for_processing</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="identifier">retrieve_data</phrase><phrase role="special">();</phrase>
|
|
<phrase role="identifier">prepare_data</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">{</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">lock_guard</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="special">></phrase> <phrase role="identifier">lk</phrase><phrase role="special">(</phrase> <phrase role="identifier">mtx</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">data_ready</phrase> <phrase role="special">=</phrase> <phrase role="keyword">true</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">}</phrase>
|
|
<phrase role="identifier">cond</phrase><phrase role="special">.</phrase><phrase role="identifier">notify_one</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">}</phrase>
|
|
</programlisting>
|
|
<para>
|
|
Note that the same mutex is locked before the shared data is updated, but
|
|
that the mutex does not have to be locked across the call to <code><phrase
|
|
role="identifier">notify_one</phrase></code>.
|
|
</para>
|
|
<para>
|
|
Locking is important because the synchronization objects provided by <emphasis
|
|
role="bold">Boost.Fiber</emphasis> can be used to synchronize fibers running
|
|
on different threads.
|
|
</para>
|
|
<para>
|
|
<emphasis role="bold">Boost.Fiber</emphasis> provides both <code><phrase
|
|
role="identifier">condition_variable</phrase></code> and <code><phrase role="identifier">condition_variable_any</phrase></code>
|
|
because <ulink url="boost:/libs/thread/index.html">Boost.Thread</ulink> provides
|
|
both. (<emphasis role="bold">Boost.Fiber</emphasis> also provides the name
|
|
<code><phrase role="identifier">condition</phrase></code>, which has been
|
|
deprecated in <ulink url="boost:/libs/thread/index.html">Boost.Thread</ulink>.)
|
|
However, <code><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">condition_variable</phrase></code> and <code><phrase role="identifier">boost</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">condition_variable_any</phrase></code>
|
|
are the same class; like <code><phrase role="identifier">boost</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">thread</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">condition_variable_any</phrase></code>,
|
|
its wait() method will accept any form of lock. <code><phrase role="identifier">boost</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">condition_variable_any</phrase></code>
|
|
has no need to further optimize as described for <code><phrase role="identifier">boost</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">thread</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">condition_variable</phrase></code>.
|
|
</para>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_condition_variable_bridgehead">
|
|
<phrase id="class_condition_variable"/>
|
|
<link linkend="class_condition_variable">Class
|
|
<code>condition_variable</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">condition</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">enum</phrase> <phrase role="identifier">cv_status</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="identifier">no_timeout</phrase> <phrase role="special">=</phrase> <phrase role="number">1</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">timeout</phrase>
|
|
<phrase role="special">};</phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">condition_variable</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">condition_variable</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">~</phrase><phrase role="identifier">condition_variable</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">condition_variable</phrase><phrase role="special">(</phrase> <phrase role="identifier">condition_variable</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">condition_variable</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">condition_variable</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">notify_one</phrase><phrase role="special">();</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">notify_all</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">LockType</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="identifier">Pred</phrase> <phrase role="identifier">predicate</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">LockType</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">cv_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">LockType</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">Pred</phrase> <phrase role="identifier">pred</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">LockType</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">cv_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">LockType</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">Pred</phrase> <phrase role="identifier">pred</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">};</phrase>
|
|
|
|
<phrase role="keyword">typedef</phrase> <phrase role="identifier">condition_variable</phrase> <phrase role="identifier">condition_variable_any</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect4" id="fiber.synchronization.conditions.h1">
|
|
<phrase id="fiber.synchronization.conditions.constructor"/><link linkend="fiber.synchronization.conditions.constructor">Constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">condition_variable</phrase><phrase role="special">()</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Creates the object.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect4" id="fiber.synchronization.conditions.h2">
|
|
<phrase id="fiber.synchronization.conditions.destructor"/><link linkend="fiber.synchronization.conditions.destructor">Destructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="special">~</phrase><phrase role="identifier">condition_variable</phrase><phrase role="special">()</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
All fibers waiting on <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code> have been notified by a call to
|
|
<code><phrase role="identifier">notify_one</phrase></code> or <code><phrase
|
|
role="identifier">notify_all</phrase></code> (though the respective
|
|
calls to <code><phrase role="identifier">wait</phrase></code>, <code><phrase
|
|
role="identifier">wait_for</phrase></code> or <code><phrase role="identifier">wait_until</phrase></code>
|
|
need not have returned).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Destroys the object.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="condition_variable_notify_one_bridgehead">
|
|
<phrase id="condition_variable_notify_one"/>
|
|
<link linkend="condition_variable_notify_one">Member
|
|
function <code>notify_one</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">notify_one</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
If any fibers are currently <link linkend="blocking"><emphasis>blocked</emphasis></link>
|
|
waiting on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
in a call to <code><phrase role="identifier">wait</phrase></code>,
|
|
<code><phrase role="identifier">wait_for</phrase></code> or <code><phrase
|
|
role="identifier">wait_until</phrase></code>, unblocks one of those
|
|
fibers.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
It is arbitrary which waiting fiber is resumed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="condition_variable_notify_all_bridgehead">
|
|
<phrase id="condition_variable_notify_all"/>
|
|
<link linkend="condition_variable_notify_all">Member
|
|
function <code>notify_all</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">notify_all</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
If any fibers are currently <link linkend="blocking"><emphasis>blocked</emphasis></link>
|
|
waiting on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
in a call to <code><phrase role="identifier">wait</phrase></code>,
|
|
<code><phrase role="identifier">wait_for</phrase></code> or <code><phrase
|
|
role="identifier">wait_until</phrase></code>, unblocks all of those
|
|
fibers.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
This is why a waiting fiber must <emphasis>also</emphasis> check for
|
|
the desired program state using a mechanism external to the <code><phrase
|
|
role="identifier">condition_variable</phrase></code>, and retry the
|
|
wait until that state is reached. A fiber waiting on a <code><phrase
|
|
role="identifier">condition_variable</phrase></code> might well wake
|
|
up a number of times before the desired state is reached.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="condition_variable_wait_bridgehead">
|
|
<phrase id="condition_variable_wait"/>
|
|
<link linkend="condition_variable_wait">Templated
|
|
member function <code>wait</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">LockType</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="identifier">Pred</phrase> <phrase role="identifier">pred</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">lk</phrase></code> is locked by the
|
|
current fiber, and either no other fiber is currently waiting on <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>,
|
|
or the execution of the <code><phrase role="identifier">mutex</phrase><phrase
|
|
role="special">()</phrase></code> member function on the <code><phrase
|
|
role="identifier">lk</phrase></code> objects supplied in the calls
|
|
to <code><phrase role="identifier">wait</phrase></code> in all the
|
|
fibers currently waiting on <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code> would return the same value as
|
|
<code><phrase role="identifier">lk</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">mutex</phrase><phrase role="special">()</phrase></code>
|
|
for this call to <code><phrase role="identifier">wait</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Atomically call <code><phrase role="identifier">lk</phrase><phrase
|
|
role="special">.</phrase><phrase role="identifier">unlock</phrase><phrase
|
|
role="special">()</phrase></code> and blocks the current fiber. The
|
|
fiber will unblock when notified by a call to <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">notify_one</phrase><phrase
|
|
role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">notify_all</phrase><phrase
|
|
role="special">()</phrase></code>, or spuriously. When the fiber is
|
|
unblocked (for whatever reason), the lock is reacquired by invoking
|
|
<code><phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">lock</phrase><phrase role="special">()</phrase></code>
|
|
before the call to <code><phrase role="identifier">wait</phrase></code>
|
|
returns. The lock is also reacquired by invoking <code><phrase role="identifier">lk</phrase><phrase
|
|
role="special">.</phrase><phrase role="identifier">lock</phrase><phrase
|
|
role="special">()</phrase></code> if the function exits with an exception.
|
|
The member function accepting <code><phrase role="identifier">pred</phrase></code>
|
|
is shorthand for:
|
|
<programlisting><phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">pred</phrase><phrase role="special">())</phrase>
|
|
<phrase role="special">{</phrase>
|
|
<phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">}</phrase>
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postcondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">lk</phrase></code> is locked by the
|
|
current fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_exception</phrase></code> if
|
|
an error occurs. <code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
if the wait was interrupted by a call to <link linkend="fiber_interrupt"> <code>fiber::interrupt()</code></link> on
|
|
the <link linkend="class_fiber"> <code>fiber</code></link> object associated with the current fiber of execution.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
The Precondition is a bit dense. It merely states that all the fibers
|
|
calling <code><phrase role="identifier">wait</phrase></code> on <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
must wait on <code><phrase role="identifier">lk</phrase></code> objects
|
|
governing the <emphasis>same</emphasis> <code><phrase role="identifier">mutex</phrase></code>.
|
|
Three distinct objects are involved in any <code><phrase role="identifier">condition_variable</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">wait</phrase><phrase
|
|
role="special">()</phrase></code> call: the <code><phrase role="identifier">condition_variable</phrase></code>
|
|
itself, the <code><phrase role="identifier">mutex</phrase></code> coordinating
|
|
access between fibers and a lock object (e.g. <code><phrase role="identifier">std</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">lock_guard</phrase></code>).
|
|
In some sense it would be nice if the <code><phrase role="identifier">condition_variable</phrase></code>'s
|
|
constructor could accept the related <code><phrase role="identifier">mutex</phrase></code>
|
|
object, enforcing agreement across all <code><phrase role="identifier">wait</phrase><phrase
|
|
role="special">()</phrase></code> calls; but the existing APIs prevent
|
|
that. Instead we must require the <code><phrase role="identifier">wait</phrase><phrase
|
|
role="special">()</phrase></code> call to accept a reference to the
|
|
local lock object. It is an error to reuse a given <code><phrase role="identifier">condition_variable</phrase></code>
|
|
instance with lock objects that reference <emphasis>different</emphasis>
|
|
underlying <code><phrase role="identifier">mutex</phrase></code> objects.
|
|
It would be like a road intersection with traffic lights independent
|
|
of one another: sooner or later a collision will result.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="condition_variable_wait_until_bridgehead">
|
|
<phrase id="condition_variable_wait_until"/>
|
|
<link linkend="condition_variable_wait_until">Templated
|
|
member function <code>wait_until</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">LockType</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">cv_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">LockType</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">Pred</phrase> <phrase role="identifier">pred</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">lk</phrase></code> is locked by the
|
|
current fiber, and either no other fiber is currently waiting on <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>,
|
|
or the execution of the <code><phrase role="identifier">mutex</phrase><phrase
|
|
role="special">()</phrase></code> member function on the <code><phrase
|
|
role="identifier">lk</phrase></code> objects supplied in the calls
|
|
to <code><phrase role="identifier">wait</phrase></code>, <code><phrase
|
|
role="identifier">wait_for</phrase></code> or <code><phrase role="identifier">wait_until</phrase></code>
|
|
in all the fibers currently waiting on <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code> would return the same value as
|
|
<code><phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">mutex</phrase><phrase role="special">()</phrase></code>
|
|
for this call to <code><phrase role="identifier">wait_until</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Atomically call <code><phrase role="identifier">lk</phrase><phrase
|
|
role="special">.</phrase><phrase role="identifier">unlock</phrase><phrase
|
|
role="special">()</phrase></code> and blocks the current fiber. The
|
|
fiber will unblock when notified by a call to <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">notify_one</phrase><phrase
|
|
role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">notify_all</phrase><phrase
|
|
role="special">()</phrase></code>, when the system time would be equal
|
|
to or later than the specified <code><phrase role="identifier">timeout_time</phrase></code>,
|
|
or spuriously. When the fiber is unblocked (for whatever reason), the
|
|
lock is reacquired by invoking <code><phrase role="identifier">lk</phrase><phrase
|
|
role="special">.</phrase><phrase role="identifier">lock</phrase><phrase
|
|
role="special">()</phrase></code> before the call to <code><phrase
|
|
role="identifier">wait_until</phrase></code> returns. The lock is also
|
|
reacquired by invoking <code><phrase role="identifier">lk</phrase><phrase
|
|
role="special">.</phrase><phrase role="identifier">lock</phrase><phrase
|
|
role="special">()</phrase></code> if the function exits with an exception.
|
|
The member function accepting <code><phrase role="identifier">pred</phrase></code>
|
|
is shorthand for:
|
|
<programlisting><phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">pred</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase>
|
|
<phrase role="special">{</phrase>
|
|
<phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase role="identifier">timeout</phrase> <phrase role="special">==</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase>
|
|
<phrase role="keyword">return</phrase> <phrase role="identifier">pred</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">}</phrase>
|
|
<phrase role="keyword">return</phrase> <phrase role="keyword">true</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
That is, even if <code><phrase role="identifier">wait_until</phrase><phrase
|
|
role="special">()</phrase></code> times out, it can still return <code><phrase
|
|
role="keyword">true</phrase></code> if <code><phrase role="identifier">pred</phrase><phrase
|
|
role="special">()</phrase></code> returns <code><phrase role="keyword">true</phrase></code>
|
|
at that time.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postcondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">lk</phrase></code> is locked by the
|
|
current fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_exception</phrase></code> if
|
|
an error occurs. <code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
if the wait was interrupted by a call to <link linkend="fiber_interrupt"> <code>fiber::interrupt()</code></link> on
|
|
the <link linkend="class_fiber"> <code>fiber</code></link> object associated with the current fiber of execution.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
The overload without <code><phrase role="identifier">pred</phrase></code>
|
|
returns <code><phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">no_timeout</phrase></code> if awakened by <code><phrase
|
|
role="identifier">notify_one</phrase><phrase role="special">()</phrase></code>
|
|
or <code><phrase role="identifier">notify_all</phrase><phrase role="special">()</phrase></code>,
|
|
or <code><phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">timeout</phrase></code> if awakened because the system
|
|
time is past <code><phrase role="identifier">timeout_time</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
The overload accepting <code><phrase role="identifier">pred</phrase></code>
|
|
returns <code><phrase role="keyword">false</phrase></code> if the call
|
|
is returning because the time specified by <code><phrase role="identifier">timeout_time</phrase></code>
|
|
was reached and the predicate returns <code><phrase role="keyword">false</phrase></code>,
|
|
<code><phrase role="keyword">true</phrase></code> otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
See <emphasis role="bold">Note</emphasis> for <link linkend="condition_variable_wait"> <code>condition_variable::wait()</code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="condition_variable_wait_for_bridgehead">
|
|
<phrase id="condition_variable_wait_for"/>
|
|
<link linkend="condition_variable_wait_for">Templated
|
|
member function <code>wait_for</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">LockType</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">cv_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">LockType</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">LockType</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">Pred</phrase> <phrase role="identifier">pred</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">lk</phrase></code> is locked by the
|
|
current fiber, and either no other fiber is currently waiting on <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>,
|
|
or the execution of the <code><phrase role="identifier">mutex</phrase><phrase
|
|
role="special">()</phrase></code> member function on the <code><phrase
|
|
role="identifier">lk</phrase></code> objects supplied in the calls
|
|
to <code><phrase role="identifier">wait</phrase></code>, <code><phrase
|
|
role="identifier">wait_for</phrase></code> or <code><phrase role="identifier">wait_until</phrase></code>
|
|
in all the fibers currently waiting on <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code> would return the same value as
|
|
<code><phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">mutex</phrase><phrase role="special">()</phrase></code>
|
|
for this call to <code><phrase role="identifier">wait_for</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Atomically call <code><phrase role="identifier">lk</phrase><phrase
|
|
role="special">.</phrase><phrase role="identifier">unlock</phrase><phrase
|
|
role="special">()</phrase></code> and blocks the current fiber. The
|
|
fiber will unblock when notified by a call to <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">notify_one</phrase><phrase
|
|
role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">notify_all</phrase><phrase
|
|
role="special">()</phrase></code>, when a time interval equal to or
|
|
greater than the specified <code><phrase role="identifier">timeout_duration</phrase></code>
|
|
has elapsed, or spuriously. When the fiber is unblocked (for whatever
|
|
reason), the lock is reacquired by invoking <code><phrase role="identifier">lk</phrase><phrase
|
|
role="special">.</phrase><phrase role="identifier">lock</phrase><phrase
|
|
role="special">()</phrase></code> before the call to <code><phrase
|
|
role="identifier">wait</phrase></code> returns. The lock is also reacquired
|
|
by invoking <code><phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">lock</phrase><phrase role="special">()</phrase></code>
|
|
if the function exits with an exception. The <code><phrase role="identifier">wait_for</phrase><phrase
|
|
role="special">()</phrase></code> member function accepting <code><phrase
|
|
role="identifier">pred</phrase></code> is shorthand for:
|
|
<programlisting><phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">pred</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase role="identifier">timeout</phrase> <phrase role="special">==</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">return</phrase> <phrase role="identifier">pred</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">}</phrase>
|
|
<phrase role="special">}</phrase>
|
|
<phrase role="keyword">return</phrase> <phrase role="keyword">true</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
That is, even if <code><phrase role="identifier">wait_for</phrase><phrase
|
|
role="special">()</phrase></code> times out, it can still return <code><phrase
|
|
role="keyword">true</phrase></code> if <code><phrase role="identifier">pred</phrase><phrase
|
|
role="special">()</phrase></code> returns <code><phrase role="keyword">true</phrase></code>
|
|
at that time.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postcondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">lk</phrase></code> is locked by the
|
|
current fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_exception</phrase></code> if
|
|
an error occurs. <code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
if the wait was interrupted by a call to <link linkend="fiber_interrupt"> <code>fiber::interrupt()</code></link> on
|
|
the <link linkend="class_fiber"> <code>fiber</code></link> object associated with the current fiber of execution.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
The overload without <code><phrase role="identifier">pred</phrase></code>
|
|
returns <code><phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">no_timeout</phrase></code> if awakened by <code><phrase
|
|
role="identifier">notify_one</phrase><phrase role="special">()</phrase></code>
|
|
or <code><phrase role="identifier">notify_all</phrase><phrase role="special">()</phrase></code>,
|
|
or <code><phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">timeout</phrase></code> if awakened because at least
|
|
<code><phrase role="identifier">timeout_duration</phrase></code> has
|
|
elapsed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
The overload accepting <code><phrase role="identifier">pred</phrase></code>
|
|
returns <code><phrase role="keyword">false</phrase></code> if the call
|
|
is returning because at least <code><phrase role="identifier">timeout_duration</phrase></code>
|
|
has elapsed and the predicate returns <code><phrase role="keyword">false</phrase></code>,
|
|
<code><phrase role="keyword">true</phrase></code> otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
See <emphasis role="bold">Note</emphasis> for <link linkend="condition_variable_wait"> <code>condition_variable::wait()</code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
<section id="fiber.synchronization.barriers">
|
|
<title><link linkend="fiber.synchronization.barriers">Barriers</link></title>
|
|
<para>
|
|
A barrier is a concept also known as a <emphasis>rendezvous</emphasis>, it
|
|
is a synchronization point between multiple contexts of execution (fibers).
|
|
The barrier is configured for a particular number of fibers (<code><phrase
|
|
role="identifier">n</phrase></code>), and as fibers reach the barrier they
|
|
must wait until all <code><phrase role="identifier">n</phrase></code> fibers
|
|
have arrived. Once the <code><phrase role="identifier">n</phrase></code>-th
|
|
fiber has reached the barrier, all the waiting fibers can proceed, and the
|
|
barrier is reset.
|
|
</para>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_barrier_bridgehead">
|
|
<phrase id="class_barrier"/>
|
|
<link linkend="class_barrier">Class <code>barrier</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">barrier</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">barrier</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">barrier</phrase><phrase role="special">(</phrase> <phrase role="keyword">unsigned</phrase> <phrase role="keyword">int</phrase> <phrase role="identifier">initial</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="identifier">barrier</phrase><phrase role="special">(</phrase> <phrase role="identifier">barrier</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">barrier</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">barrier</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">wait</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<para>
|
|
Instances of <link linkend="class_barrier"> <code>barrier</code></link> are not copyable or movable.
|
|
</para>
|
|
<bridgehead renderas="sect4" id="fiber.synchronization.barriers.h0">
|
|
<phrase id="fiber.synchronization.barriers.constructor"/><link linkend="fiber.synchronization.barriers.constructor">Constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">barrier</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">initial</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Construct a barrier for <code><phrase role="identifier">initial</phrase></code>
|
|
fibers.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">invalid_argument</phrase></code> if <code><phrase
|
|
role="identifier">initial</phrase></code> is zero
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="barrier_wait_bridgehead">
|
|
<phrase id="barrier_wait"/>
|
|
<link linkend="barrier_wait">Member function <code>wait</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">wait</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Block until <code><phrase role="identifier">initial</phrase></code>
|
|
fibers have called <code><phrase role="identifier">wait</phrase></code>
|
|
on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>.
|
|
When the <code><phrase role="identifier">initial</phrase></code>-th
|
|
fiber calls <code><phrase role="identifier">wait</phrase></code>, all
|
|
waiting fibers are unblocked, and the barrier is reset.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase></code> for exactly one fiber
|
|
from each batch of waiting fibers, <code><phrase role="keyword">false</phrase></code>
|
|
otherwise.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_exception</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Notes:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">wait</phrase><phrase role="special">()</phrase></code>
|
|
is one of the predefined <link linkend="interruption"><emphasis>interruption-points</emphasis></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
<section id="fiber.synchronization.channels">
|
|
<title><link linkend="fiber.synchronization.channels">Channels</link></title>
|
|
<para>
|
|
<emphasis role="bold">Boost.Fiber</emphasis> provides a bounded and a unbounded
|
|
channel suitable to synchonize fibers via message passing.
|
|
</para>
|
|
<programlisting><phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="keyword">int</phrase> <phrase role="special">></phrase> <phrase role="identifier">channel_t</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">send</phrase><phrase role="special">(</phrase> <phrase role="identifier">channel_t</phrase> <phrase role="special">&</phrase> <phrase role="identifier">channel</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">for</phrase> <phrase role="special">(</phrase> <phrase role="keyword">int</phrase> <phrase role="identifier">i</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> <phrase role="identifier">i</phrase> <phrase role="special"><</phrase> <phrase role="number">5</phrase><phrase role="special">;</phrase> <phrase role="special">++</phrase><phrase role="identifier">i</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="identifier">channel</phrase><phrase role="special">.</phrase><phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">i</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">}</phrase>
|
|
<phrase role="identifier">channel</phrase><phrase role="special">.</phrase><phrase role="identifier">close</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">}</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">recv</phrase><phrase role="special">(</phrase> <phrase role="identifier">channel_t</phrase> <phrase role="special">&</phrase> <phrase role="identifier">channel</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">int</phrase> <phrase role="identifier">i</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">channel_op_status</phrase><phrase role="special">::</phrase><phrase role="identifier">success</phrase> <phrase role="special">==</phrase> <phrase role="identifier">channel</phrase><phrase role="special">.</phrase><phrase role="identifier">pop</phrase><phrase role="special">(</phrase><phrase role="identifier">i</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"received "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">i</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">}</phrase>
|
|
<phrase role="special">}</phrase>
|
|
|
|
<phrase role="identifier">channel_t</phrase> <phrase role="identifier">channel</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f1</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">bind</phrase><phrase role="special">(</phrase> <phrase role="identifier">send</phrase><phrase role="special">,</phrase> <phrase role="identifier">ref</phrase><phrase role="special">(</phrase> <phrase role="identifier">channel</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">);</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f2</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">bind</phrase><phrase role="special">(</phrase> <phrase role="identifier">recv</phrase><phrase role="special">,</phrase> <phrase role="identifier">ref</phrase><phrase role="special">(</phrase> <phrase role="identifier">channel</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">);</phrase>
|
|
|
|
<phrase role="identifier">f1</phrase><phrase role="special">.</phrase><phrase role="identifier">join</phrase><phrase role="special">();</phrase>
|
|
<phrase role="identifier">f2</phrase><phrase role="special">.</phrase><phrase role="identifier">join</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<anchor id="class_channel_op_status"/>
|
|
<bridgehead renderas="sect4" id="fiber.synchronization.channels.h0">
|
|
<phrase id="fiber.synchronization.channels.enumeration__code__phrase_role__identifier__channel_op_status__phrase___code_"/><link
|
|
linkend="fiber.synchronization.channels.enumeration__code__phrase_role__identifier__channel_op_status__phrase___code_">Enumeration
|
|
<code><phrase role="identifier">channel_op_status</phrase></code></link>
|
|
</bridgehead>
|
|
<para>
|
|
channel operations return the state of the channel.
|
|
</para>
|
|
<programlisting><phrase role="keyword">enum</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">channel_op_status</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="identifier">success</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">empty</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">full</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">closed</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">timeout</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect4" id="fiber.synchronization.channels.h1">
|
|
<phrase id="fiber.synchronization.channels._code__phrase_role__identifier__success__phrase___code_"/><link
|
|
linkend="fiber.synchronization.channels._code__phrase_role__identifier__success__phrase___code_"><code><phrase
|
|
role="identifier">success</phrase></code></link>
|
|
</bridgehead>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Operation was successful.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect4" id="fiber.synchronization.channels.h2">
|
|
<phrase id="fiber.synchronization.channels._code__phrase_role__identifier__empty__phrase___code_"/><link
|
|
linkend="fiber.synchronization.channels._code__phrase_role__identifier__empty__phrase___code_"><code><phrase
|
|
role="identifier">empty</phrase></code></link>
|
|
</bridgehead>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
channel is empty, operation failed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect4" id="fiber.synchronization.channels.h3">
|
|
<phrase id="fiber.synchronization.channels._code__phrase_role__identifier__full__phrase___code_"/><link
|
|
linkend="fiber.synchronization.channels._code__phrase_role__identifier__full__phrase___code_"><code><phrase
|
|
role="identifier">full</phrase></code></link>
|
|
</bridgehead>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
channel is full, operation failed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect4" id="fiber.synchronization.channels.h4">
|
|
<phrase id="fiber.synchronization.channels._code__phrase_role__identifier__closed__phrase___code_"/><link
|
|
linkend="fiber.synchronization.channels._code__phrase_role__identifier__closed__phrase___code_"><code><phrase
|
|
role="identifier">closed</phrase></code></link>
|
|
</bridgehead>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
channel is closed, operation failed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect4" id="fiber.synchronization.channels.h5">
|
|
<phrase id="fiber.synchronization.channels._code__phrase_role__identifier__timeout__phrase___code_"/><link
|
|
linkend="fiber.synchronization.channels._code__phrase_role__identifier__timeout__phrase___code_"><code><phrase
|
|
role="identifier">timeout</phrase></code></link>
|
|
</bridgehead>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
The operation did not become ready before specified timeout elapsed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_unbounded_channel_bridgehead">
|
|
<phrase id="class_unbounded_channel"/>
|
|
<link linkend="class_unbounded_channel">Template
|
|
<code>unbounded_channel<></code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">unbounded_channel</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="keyword">typedef</phrase> <phrase role="identifier">T</phrase> <phrase role="identifier">value_type</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">unbounded_channel</phrase><phrase role="special">(</phrase> <phrase role="identifier">unbounded_channel</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">unbounded_channel</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">unbounded_channel</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">close</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">value_type</phrase> <phrase role="identifier">value_pop</phrase><phrase role="special">();</phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">try_pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="unbounded_channel_close_bridgehead">
|
|
<phrase id="unbounded_channel_close"/>
|
|
<link linkend="unbounded_channel_close">Member
|
|
function <code>close</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">close</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Deactivates the channel. No values can be put after calling <code><phrase
|
|
role="keyword">this</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">close</phrase><phrase role="special">()</phrase></code>.
|
|
Fibers blocked in <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">pop</phrase><phrase
|
|
role="special">()</phrase></code>, <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">pop_wait_for</phrase><phrase
|
|
role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">pop_wait_until</phrase><phrase
|
|
role="special">()</phrase></code> will return <code><phrase role="identifier">closed</phrase></code>.
|
|
Fibers blocked in <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">value_pop</phrase><phrase
|
|
role="special">()</phrase></code> will receive an exception.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">close</phrase><phrase role="special">()</phrase></code>
|
|
is like closing a pipe. It informs waiting consumers that no more values
|
|
will arrive.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="unbounded_channel_push_bridgehead">
|
|
<phrase id="unbounded_channel_push"/>
|
|
<link linkend="unbounded_channel_push">Member
|
|
function <code>push</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
If channel is not closed, Otherwise enqueues the value in the channel,
|
|
wakes up a fiber blocked on <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">pop</phrase><phrase
|
|
role="special">()</phrase></code>, <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">value_pop</phrase><phrase
|
|
role="special">()</phrase></code>, <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">pop_wait_for</phrase><phrase
|
|
role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">pop_wait_until</phrase><phrase
|
|
role="special">()</phrase></code> and returns <code><phrase role="identifier">success</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="unbounded_channel_pop_bridgehead">
|
|
<phrase id="unbounded_channel_pop"/>
|
|
<link linkend="unbounded_channel_pop">Member
|
|
function <code>pop</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Dequeues a value from the channel. If the channel is empty, the fiber
|
|
gets suspended until at least one new item is <code><phrase role="identifier">push</phrase><phrase
|
|
role="special">()</phrase></code>ed (return value <code><phrase role="identifier">success</phrase></code>
|
|
and <code><phrase role="identifier">va</phrase></code> contains dequeued
|
|
value) or the channel gets <code><phrase role="identifier">close</phrase><phrase
|
|
role="special">()</phrase></code>d (return value <code><phrase role="identifier">closed</phrase></code>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="unbounded_channel_value_pop_bridgehead">
|
|
<phrase id="unbounded_channel_value_pop"/>
|
|
<link linkend="unbounded_channel_value_pop">Member
|
|
function <code>value_pop</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">value_type</phrase> <phrase role="identifier">value_pop</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Dequeues a value from the channel. If the channel is empty, the fiber
|
|
gets suspended until at least one new item is <code><phrase role="identifier">push</phrase><phrase
|
|
role="special">()</phrase></code>ed or the channel gets <code><phrase
|
|
role="identifier">close</phrase><phrase role="special">()</phrase></code>d
|
|
(which throws an exception).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">logic_error</phrase></code> if <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
is closed; <code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="unbounded_channel_try_pop_bridgehead">
|
|
<phrase id="unbounded_channel_try_pop"/>
|
|
<link linkend="unbounded_channel_try_pop">Member
|
|
function <code>try_pop</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">try_pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
If channel is empty, returns <code><phrase role="identifier">empty</phrase></code>.
|
|
If channel is closed, returns <code><phrase role="identifier">closed</phrase></code>.
|
|
Otherwise it returns <code><phrase role="identifier">success</phrase></code>
|
|
and <code><phrase role="identifier">va</phrase></code> contains the
|
|
dequeued value.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="unbounded_channel_pop_wait_for_bridgehead">
|
|
<phrase id="unbounded_channel_pop_wait_for"/>
|
|
<link linkend="unbounded_channel_pop_wait_for">Member
|
|
function <code>pop_wait_for</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Accepts <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">duration</phrase></code> and internally computes
|
|
a timeout time as (system time + <code><phrase role="identifier">timeout_duration</phrase></code>).
|
|
If channel iss not _empty, immediately dequeues a value from the channel.
|
|
Otherwise the fiber gets suspended until at least one new item is
|
|
<code><phrase role="identifier">push</phrase><phrase role="special">()</phrase></code>ed
|
|
(return value <code><phrase role="identifier">success</phrase></code>
|
|
and <code><phrase role="identifier">va</phrase></code> contains dequeued
|
|
value), or the channel gets <code><phrase role="identifier">close</phrase><phrase
|
|
role="special">()</phrase></code>d (return value <code><phrase role="identifier">closed</phrase></code>),
|
|
or the system time reaches the computed timeout time (return value
|
|
<code><phrase role="identifier">timeout</phrase></code>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="unbounded_channel_pop_wait_until_bridgehead">
|
|
<phrase id="unbounded_channel_pop_wait_until"/>
|
|
<link linkend="unbounded_channel_pop_wait_until">Member
|
|
function <code>pop_wait_until</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Accepts a <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">time_point</phrase><phrase role="special"><</phrase>
|
|
<phrase role="identifier">Clock</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">Duration</phrase> <phrase role="special">></phrase></code>.
|
|
If channel iss not _empty, immediately dequeues a value from the channel.
|
|
Otherwise the fiber gets suspended until at least one new item is
|
|
<code><phrase role="identifier">push</phrase><phrase role="special">()</phrase></code>ed
|
|
(return value <code><phrase role="identifier">success</phrase></code>
|
|
and <code><phrase role="identifier">va</phrase></code> contains dequeued
|
|
value), or the channel gets <code><phrase role="identifier">close</phrase><phrase
|
|
role="special">()</phrase></code>d (return value <code><phrase role="identifier">closed</phrase></code>),
|
|
or the system time reaches the passed <code><phrase role="identifier">time_point</phrase></code>
|
|
(return value <code><phrase role="identifier">timeout</phrase></code>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_interrupted</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_bounded_channel_bridgehead">
|
|
<phrase id="class_bounded_channel"/>
|
|
<link linkend="class_bounded_channel">Template
|
|
<code>bounded_channel<></code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">bounded_channel</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">bounded_channel</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="keyword">typedef</phrase> <phrase role="identifier">T</phrase> <phrase role="identifier">value_type</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">bounded_channel</phrase><phrase role="special">(</phrase> <phrase role="identifier">bounded_channel</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">bounded_channel</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">bounded_channel</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">bounded_channel</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">wm</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">bounded_channel</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">hwm</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">lwm</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">upper_bound</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">lower_bound</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">close</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push_wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push_wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push_wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push_wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">try_push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">try_push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">value_type</phrase> <phrase role="identifier">value_pop</phrase><phrase role="special">();</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase>
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">try_pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect4" id="fiber.synchronization.channels.h6">
|
|
<phrase id="fiber.synchronization.channels.constructor"/><link linkend="fiber.synchronization.channels.constructor">Constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">bounded_channel</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">wm</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">bounded_channel</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">hwm</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">lwm</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Preconditions:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">hwm</phrase> <phrase role="special">>=</phrase>
|
|
<phrase role="identifier">lwm</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Constructs an object of class <code><phrase role="identifier">bounded_channel</phrase></code>.
|
|
The constructor with two arguments constructs an object of class <code><phrase
|
|
role="identifier">bounded_channel</phrase></code> with a high-watermark
|
|
of <code><phrase role="identifier">hwm</phrase></code> and a low-watermark
|
|
of <code><phrase role="identifier">lwm</phrase></code> items. The constructor
|
|
with one argument effectively sets both <code><phrase role="identifier">hwm</phrase></code>
|
|
and <code><phrase role="identifier">lwm</phrase></code> to the same
|
|
value <code><phrase role="identifier">wm</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">invalid_argument</phrase></code> if
|
|
<code><phrase role="identifier">lwm</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">hwm</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Notes:</term>
|
|
<listitem>
|
|
<para>
|
|
Once the number of values in the channel reaches <code><phrase role="identifier">hwm</phrase></code>,
|
|
any call to <code><phrase role="identifier">push</phrase><phrase role="special">()</phrase></code>,
|
|
<code><phrase role="identifier">push_wait_for</phrase><phrase role="special">()</phrase></code>
|
|
or <code><phrase role="identifier">push_wait_until</phrase><phrase
|
|
role="special">()</phrase></code> will block until the number of values
|
|
in the channel has dropped below <code><phrase role="identifier">lwm</phrase></code>.
|
|
That is, if <code><phrase role="identifier">lwm</phrase> <phrase role="special"><</phrase>
|
|
<phrase role="identifier">hwm</phrase></code>, the channel can be in
|
|
a state in which <code><phrase role="identifier">push</phrase><phrase
|
|
role="special">()</phrase></code>, <code><phrase role="identifier">push_wait_for</phrase><phrase
|
|
role="special">()</phrase></code> or <code><phrase role="identifier">push_wait_until</phrase><phrase
|
|
role="special">()</phrase></code> calls will block (channel is full)
|
|
even though the number of values in the channel is less than <code><phrase
|
|
role="identifier">hwm</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="bounded_channel_upper_bound_bridgehead">
|
|
<phrase id="bounded_channel_upper_bound"/>
|
|
<link linkend="bounded_channel_upper_bound">Member
|
|
function <code>upper_bound</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">upper_bound</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
the high-watermark with which <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code> was constructed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="bounded_channel_lower_bound_bridgehead">
|
|
<phrase id="bounded_channel_lower_bound"/>
|
|
<link linkend="bounded_channel_lower_bound">Member
|
|
function <code>lower_bound</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">lower_bound</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
the low-watermark with which <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code> was constructed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="bounded_channel_close_bridgehead">
|
|
<phrase id="bounded_channel_close"/>
|
|
<link linkend="bounded_channel_close">Member
|
|
function <code>close</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">close</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Deactivates the channel. No values can be put after calling <code><phrase
|
|
role="keyword">this</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">close</phrase><phrase role="special">()</phrase></code>.
|
|
Fibers blocked in <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">pop</phrase><phrase
|
|
role="special">()</phrase></code>, <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">pop_wait_for</phrase><phrase
|
|
role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">pop_wait_until</phrase><phrase
|
|
role="special">()</phrase></code> will return <code><phrase role="identifier">closed</phrase></code>.
|
|
Fibers blocked in <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">value_pop</phrase><phrase
|
|
role="special">()</phrase></code> will receive an exception.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">close</phrase><phrase role="special">()</phrase></code>
|
|
is like closing a pipe. It informs waiting consumers that no more values
|
|
will arrive.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
]
|
|
</para>
|
|
</section>
|
|
<section id="fiber.synchronization.futures">
|
|
<title><link linkend="fiber.synchronization.futures">Futures</link></title>
|
|
<bridgehead renderas="sect4" id="fiber.synchronization.futures.h0">
|
|
<phrase id="fiber.synchronization.futures.overview"/><link linkend="fiber.synchronization.futures.overview">Overview</link>
|
|
</bridgehead>
|
|
<para>
|
|
The futures library provides a means of handling asynchronous future values,
|
|
whether those values are generated by another fiber, or on a single fiber
|
|
in response to external stimuli, or on-demand.
|
|
</para>
|
|
<para>
|
|
This is done through the provision of four class templates: <link linkend="class_future"> <code>future<></code></link> and
|
|
<link linkend="class_shared_future"> <code>shared_future<></code></link> which are used to retrieve the asynchronous
|
|
results, and <link linkend="class_promise"> <code>promise<></code></link> and <link linkend="class_packaged_task"> <code>packaged_task<></code></link> which
|
|
are used to generate the asynchronous results.
|
|
</para>
|
|
<para>
|
|
An instance of <link linkend="class_future"> <code>future<></code></link> holds the one and only reference
|
|
to a result. Ownership can be transferred between instances using the move
|
|
constructor or move-assignment operator, but at most one instance holds a
|
|
reference to a given asynchronous result. When the result is ready, it is
|
|
returned from <link linkend="future_get"> <code>future::get()</code></link> by rvalue-reference to allow the result
|
|
to be moved or copied as appropriate for the type.
|
|
</para>
|
|
<para>
|
|
On the other hand, many instances of <link linkend="class_shared_future"> <code>shared_future<></code></link> may
|
|
reference the same result. Instances can be freely copied and assigned, and
|
|
<link linkend="shared_future_get"> <code>shared_future::get()</code></link>
|
|
returns a <code><phrase role="keyword">const</phrase></code>
|
|
reference so that multiple calls to <link linkend="shared_future_get"> <code>shared_future::get()</code></link>
|
|
are
|
|
safe. You can move an instance of <link linkend="class_future"> <code>future<></code></link> into an instance
|
|
of <link linkend="class_shared_future"> <code>shared_future<></code></link>, thus transferring ownership
|
|
of the associated asynchronous result, but not vice-versa.
|
|
</para>
|
|
<para>
|
|
<code><phrase role="identifier">async</phrase><phrase role="special">()</phrase></code>
|
|
is a simple way of running asynchronous tasks. A call to <code><phrase role="identifier">async</phrase><phrase
|
|
role="special">()</phrase></code> returns a <link linkend="class_future"> <code>future<></code></link> that
|
|
will deliver the result of the task.
|
|
</para>
|
|
<bridgehead renderas="sect4" id="fiber.synchronization.futures.h1">
|
|
<phrase id="fiber.synchronization.futures.creating_asynchronous_values"/><link
|
|
linkend="fiber.synchronization.futures.creating_asynchronous_values">Creating
|
|
asynchronous values</link>
|
|
</bridgehead>
|
|
<para>
|
|
You can set the value in a future with either a <link linkend="class_promise"> <code>promise<></code></link> or
|
|
a <link linkend="class_packaged_task"> <code>packaged_task<></code></link>. A <link linkend="class_packaged_task"> <code>packaged_task<></code></link> is
|
|
a callable object with <code><phrase role="keyword">void</phrase></code>
|
|
return that wraps a function or callable object returning the specified type.
|
|
When the <link linkend="class_packaged_task"> <code>packaged_task<></code></link> is invoked, it invokes the
|
|
contained function in turn, and populates a future with the contained function's
|
|
return value. This is an answer to the perennial question: "How do I
|
|
return a value from a fiber?" Package the function you wish to run as
|
|
a <link linkend="class_packaged_task"> <code>packaged_task<></code></link> and pass the packaged task to the
|
|
fiber constructor. The future retrieved from the packaged task can then be
|
|
used to obtain the return value. If the function throws an exception, that
|
|
is stored in the future in place of the return value.
|
|
</para>
|
|
<programlisting><phrase role="keyword">int</phrase> <phrase role="identifier">calculate_the_answer_to_life_the_universe_and_everything</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">return</phrase> <phrase role="number">42</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">}</phrase>
|
|
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">packaged_task</phrase><phrase role="special"><</phrase><phrase role="keyword">int</phrase><phrase role="special">()></phrase> <phrase role="identifier">pt</phrase><phrase role="special">(</phrase><phrase role="identifier">calculate_the_answer_to_life_the_universe_and_everything</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase><phrase role="keyword">int</phrase><phrase role="special">></phrase> <phrase role="identifier">fi</phrase><phrase role="special">=</phrase><phrase role="identifier">pt</phrase><phrase role="special">.</phrase><phrase role="identifier">get_future</phrase><phrase role="special">();</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase><phrase role="identifier">pt</phrase><phrase role="special">)).</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase> <phrase role="comment">// launch task on a fiber</phrase>
|
|
|
|
<phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">wait</phrase><phrase role="special">();</phrase> <phrase role="comment">// wait for it to finish</phrase>
|
|
|
|
<phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">is_ready</phrase><phrase role="special">());</phrase>
|
|
<phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">has_value</phrase><phrase role="special">());</phrase>
|
|
<phrase role="identifier">assert</phrase><phrase role="special">(!</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">has_exception</phrase><phrase role="special">());</phrase>
|
|
<phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">()==</phrase><phrase role="number">42</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<para>
|
|
A <link linkend="class_promise"> <code>promise<></code></link> is a bit more low level: it just provides explicit
|
|
functions to store a value or an exception in the associated future. A promise
|
|
can therefore be used where the value might come from more than one possible
|
|
source.
|
|
</para>
|
|
<programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">promise</phrase><phrase role="special"><</phrase><phrase role="keyword">int</phrase><phrase role="special">></phrase> <phrase role="identifier">pi</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase><phrase role="keyword">int</phrase><phrase role="special">></phrase> <phrase role="identifier">fi</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">fi</phrase><phrase role="special">=</phrase><phrase role="identifier">pi</phrase><phrase role="special">.</phrase><phrase role="identifier">get_future</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">pi</phrase><phrase role="special">.</phrase><phrase role="identifier">set_value</phrase><phrase role="special">(</phrase><phrase role="number">42</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">is_ready</phrase><phrase role="special">());</phrase>
|
|
<phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">has_value</phrase><phrase role="special">());</phrase>
|
|
<phrase role="identifier">assert</phrase><phrase role="special">(!</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">has_exception</phrase><phrase role="special">());</phrase>
|
|
<phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">()==</phrase><phrase role="number">42</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<section id="fiber.synchronization.futures.future">
|
|
<title><link linkend="fiber.synchronization.futures.future">Future</link></title>
|
|
<para>
|
|
A future provides a mechanism to access the result of an asynchronous operation.
|
|
</para>
|
|
<anchor id="class_future_status"/>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h0">
|
|
<phrase id="fiber.synchronization.futures.future.enumeration__code__phrase_role__identifier__future_status__phrase___code_"/><link
|
|
linkend="fiber.synchronization.futures.future.enumeration__code__phrase_role__identifier__future_status__phrase___code_">Enumeration
|
|
<code><phrase role="identifier">future_status</phrase></code></link>
|
|
</bridgehead>
|
|
<para>
|
|
Timed wait-operations ( <link linkend="future_wait_for"> <code>future::wait_for()</code></link> and <link linkend="future_wait_until"> <code>future::wait_until()</code></link>)
|
|
return the state of the future.
|
|
</para>
|
|
<programlisting><phrase role="keyword">enum</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">future_status</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="identifier">ready</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">timeout</phrase><phrase role="special">,</phrase>
|
|
<phrase role="identifier">deferred</phrase> <phrase role="comment">// not supported yet</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h1">
|
|
<phrase id="fiber.synchronization.futures.future._code__phrase_role__identifier__ready__phrase___code_"/><link
|
|
linkend="fiber.synchronization.futures.future._code__phrase_role__identifier__ready__phrase___code_"><code><phrase
|
|
role="identifier">ready</phrase></code></link>
|
|
</bridgehead>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
The shared state is ready.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h2">
|
|
<phrase id="fiber.synchronization.futures.future._code__phrase_role__identifier__timeout__phrase___code_"/><link
|
|
linkend="fiber.synchronization.futures.future._code__phrase_role__identifier__timeout__phrase___code_"><code><phrase
|
|
role="identifier">timeout</phrase></code></link>
|
|
</bridgehead>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
The shared state did not become ready before timeout has passed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h3">
|
|
<phrase id="fiber.synchronization.futures.future._code__phrase_role__identifier__deferred__phrase___code_"/><link
|
|
linkend="fiber.synchronization.futures.future._code__phrase_role__identifier__deferred__phrase___code_"><code><phrase
|
|
role="identifier">deferred</phrase></code></link>
|
|
</bridgehead>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
The function is deferred, e.g. result will be computed only when
|
|
explictly requested.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
Not implemented yet.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<warning>
|
|
<para>
|
|
Launch policy <code><phrase role="identifier">deferred</phrase></code>,
|
|
which indicates you simply want to defer the function call until a later
|
|
time (lazy evaluation), is not supported yet.
|
|
</para>
|
|
</warning>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_future_bridgehead">
|
|
<phrase id="class_future"/>
|
|
<link linkend="class_future">Template <code>future<></code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<para>
|
|
A <link linkend="class_future"> <code>future<></code></link> contains a shared state which is not shared
|
|
with any other future.
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">future</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">future</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">future</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">future</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="special">~</phrase><phrase role="identifier">future</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">future</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">valid</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">shared_future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="identifier">share</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">R</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of generic future template</phrase>
|
|
<phrase role="identifier">R</phrase> <phrase role="special">&</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of future< R & > template specialization</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of future< void > template specialization</phrase>
|
|
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase> <phrase role="identifier">get_exception_ptr</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h4">
|
|
<phrase id="fiber.synchronization.futures.future.default_constructor"/><link
|
|
linkend="fiber.synchronization.futures.future.default_constructor">Default
|
|
constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">future</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Creates a future with no shared state. After construction is <code><phrase
|
|
role="keyword">false</phrase> <phrase role="special">==</phrase>
|
|
<phrase role="identifier">vaild</phrase><phrase role="special">()</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h5">
|
|
<phrase id="fiber.synchronization.futures.future.move_constructor"/><link
|
|
linkend="fiber.synchronization.futures.future.move_constructor">Move constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">future</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Constructs a future with the shared state of other. After construction
|
|
is <code><phrase role="keyword">false</phrase> <phrase role="special">==</phrase>
|
|
<phrase role="identifier">other</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">valid</phrase><phrase role="special">()</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h6">
|
|
<phrase id="fiber.synchronization.futures.future.destructor"/><link linkend="fiber.synchronization.futures.future.destructor">Destructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="special">~</phrase><phrase role="identifier">future</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Destructs the future; ownership is abandoned.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="future_operator_assign_bridgehead">
|
|
<phrase id="future_operator_assign"/>
|
|
<link linkend="future_operator_assign">Member
|
|
function <code>operator=</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Moves the shared state of other to <code><phrase role="keyword">this</phrase></code>.
|
|
After construction is <code><phrase role="keyword">false</phrase>
|
|
<phrase role="special">==</phrase> <phrase role="identifier">other</phrase><phrase
|
|
role="special">.</phrase><phrase role="identifier">valid</phrase><phrase
|
|
role="special">()</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="future_valid_bridgehead">
|
|
<phrase id="future_valid"/>
|
|
<link linkend="future_valid">Member function <code>valid</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">valid</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Returns <code><phrase role="keyword">true</phrase></code> if future
|
|
contains a shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="future_share_bridgehead">
|
|
<phrase id="future_share"/>
|
|
<link linkend="future_share">Member function <code>share</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">shared_future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="identifier">share</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Move the state to a <link linkend="class_shared_future"> <code>shared_future<></code></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
error condition <code><phrase role="identifier">future_errc</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">no_state</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="future_get_bridgehead">
|
|
<phrase id="future_get"/>
|
|
<link linkend="future_get">Member function <code>get</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">R</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of generic future template</phrase>
|
|
<phrase role="identifier">R</phrase> <phrase role="special">&</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of future< R & > template specialization</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of future< void > template specialization</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase> <phrase role="special">==</phrase>
|
|
<phrase role="identifier">valid</phrase><phrase role="special">()</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
the result. If result not yet set, waits.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postcondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">false</phrase> <phrase role="special">==</phrase>
|
|
<phrase role="identifier">valid</phrase><phrase role="special">()</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
error condition <code><phrase role="identifier">future_errc</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">no_state</phrase></code>
|
|
or <code><phrase role="identifier">fiber_interrupted</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="future_get_exception_ptr_bridgehead">
|
|
<phrase id="future_get_exception_ptr"/>
|
|
<link linkend="future_get_exception_ptr">Member
|
|
function <code>get_exception_ptr</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase> <phrase role="identifier">get_exception_ptr</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase> <phrase role="special">==</phrase>
|
|
<phrase role="identifier">valid</phrase><phrase role="special">()</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
the exception pointer, if set. If no result is set, waits.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
error condition <code><phrase role="identifier">future_errc</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">no_state</phrase></code>
|
|
or <code><phrase role="identifier">fiber_interrupted</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="future_wait_bridgehead">
|
|
<phrase id="future_wait"/>
|
|
<link linkend="future_wait">Member function <code>wait</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Waits for the result will become available.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
error condition <code><phrase role="identifier">future_errc</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">no_state</phrase></code>
|
|
or <code><phrase role="identifier">fiber_interrupted</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="future_wait_for_bridgehead">
|
|
<phrase id="future_wait_for"/>
|
|
<link linkend="future_wait_for">Templated member
|
|
function <code>wait_for</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Waits for the result will become available or <code><phrase role="identifier">timeout_duration</phrase></code>
|
|
has passed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Result:</term>
|
|
<listitem>
|
|
<para>
|
|
A <code><phrase role="identifier">future_status</phrase></code> is
|
|
returned indicating the reason for returning.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
error condition <code><phrase role="identifier">future_errc</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">no_state</phrase></code>
|
|
or <code><phrase role="identifier">fiber_interrupted</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="future_wait_until_bridgehead">
|
|
<phrase id="future_wait_until"/>
|
|
<link linkend="future_wait_until">Member function
|
|
<code>wait_until</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Waits for the result will become available or <code><phrase role="identifier">timeout_time</phrase></code>
|
|
has passed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Result:</term>
|
|
<listitem>
|
|
<para>
|
|
A <code><phrase role="identifier">future_status</phrase></code> is
|
|
returned indicating the reason for returning.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
error condition <code><phrase role="identifier">future_errc</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">no_state</phrase></code>
|
|
or <code><phrase role="identifier">fiber_interrupted</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_shared_future_bridgehead">
|
|
<phrase id="class_shared_future"/>
|
|
<link linkend="class_shared_future">Template
|
|
<code>shared_future<></code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<para>
|
|
A <link linkend="class_shared_future"> <code>shared_future<></code></link> contains a shared state which
|
|
might be shared with other futures.
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">shared_future</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="special">~</phrase><phrase role="identifier">shared_future</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">shared_future</phrase><phrase role="special">(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="identifier">shared_future</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">shared_future</phrase><phrase role="special">(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">shared_future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">shared_future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">shared_future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">valid</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">R</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of generic shared_future template</phrase>
|
|
<phrase role="identifier">R</phrase> <phrase role="special">&</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of shared_future< R & > template specialization</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of shared_future< void > template specialization</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h7">
|
|
<phrase id="fiber.synchronization.futures.future.default_constructor0"/><link
|
|
linkend="fiber.synchronization.futures.future.default_constructor0">Default
|
|
constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">shared_future</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Creates a future with no shared state. After construction is <code><phrase
|
|
role="keyword">false</phrase> <phrase role="special">==</phrase>
|
|
<phrase role="identifier">vaild</phrase><phrase role="special">()</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h8">
|
|
<phrase id="fiber.synchronization.futures.future.move_constructor0"/><link
|
|
linkend="fiber.synchronization.futures.future.move_constructor0">Move constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">shared_future</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">shared_future</phrase><phrase role="special">(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Constructs a future with the shared state of other. After construction
|
|
is <code><phrase role="keyword">false</phrase> <phrase role="special">==</phrase>
|
|
<phrase role="identifier">other</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">valid</phrase><phrase role="special">()</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h9">
|
|
<phrase id="fiber.synchronization.futures.future.copy_constructor"/><link
|
|
linkend="fiber.synchronization.futures.future.copy_constructor">Copy constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">shared_future</phrase><phrase role="special">(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Constructs a future with the shared state of other. After construction
|
|
is <code><phrase role="keyword">true</phrase> <phrase role="special">==</phrase>
|
|
<phrase role="identifier">other</phrase><phrase role="special">.</phrase><phrase
|
|
role="identifier">valid</phrase><phrase role="special">()</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h10">
|
|
<phrase id="fiber.synchronization.futures.future.destructor0"/><link linkend="fiber.synchronization.futures.future.destructor0">Destructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="special">~</phrase><phrase role="identifier">shared_future</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Destructs the future; ownership is abandoned if not shared.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="shared_future_operator_assign_bridgehead">
|
|
<phrase id="shared_future_operator_assign"/>
|
|
<link linkend="shared_future_operator_assign">Member
|
|
function <code>operator=</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">shared_future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">shared_future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">shared_future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Transfers the ownership of shared state according to:
|
|
<programlisting><phrase role="identifier">shared_future</phrase> <phrase role="identifier">tmp</phrase><phrase role="special">(</phrase> <phrase role="identifier">other</phrase><phrase role="special">);</phrase>
|
|
<phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">tmp</phrase><phrase role="special">);</phrase>
|
|
<phrase role="keyword">return</phrase> <phrase role="special">*</phrase> <phrase role="keyword">this</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="shared_future_valid_bridgehead">
|
|
<phrase id="shared_future_valid"/>
|
|
<link linkend="shared_future_valid">Member
|
|
function <code>valid</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">valid</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Returns <code><phrase role="keyword">true</phrase></code> if future
|
|
contains a shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="shared_future_get_bridgehead">
|
|
<phrase id="shared_future_get"/>
|
|
<link linkend="shared_future_get">Member function
|
|
<code>get</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">R</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of generic shared_future template</phrase>
|
|
<phrase role="identifier">R</phrase> <phrase role="special">&</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of shared_future< R & > template specialization</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of shared_future< void > template specialization</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase> <phrase role="special">==</phrase>
|
|
<phrase role="identifier">valid</phrase><phrase role="special">()</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Returns the result.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postcondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">false</phrase> <phrase role="special">==</phrase>
|
|
<phrase role="identifier">valid</phrase><phrase role="special">()</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
error condition <code><phrase role="identifier">future_errc</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">no_state</phrase></code>
|
|
or <code><phrase role="identifier">fiber_interrupted</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="shared_future_get_exception_ptr_bridgehead">
|
|
<phrase id="shared_future_get_exception_ptr"/>
|
|
<link linkend="shared_future_get_exception_ptr">Member
|
|
function <code>get_exception_ptr</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase> <phrase role="identifier">get_exception_ptr</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Precondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">true</phrase> <phrase role="special">==</phrase>
|
|
<phrase role="identifier">valid</phrase><phrase role="special">()</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
the exception pointer, if set. If no result is set, waits.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
error condition <code><phrase role="identifier">future_errc</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">no_state</phrase></code>
|
|
or <code><phrase role="identifier">fiber_interrupted</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="shared_future_wait_bridgehead">
|
|
<phrase id="shared_future_wait"/>
|
|
<link linkend="shared_future_wait">Member
|
|
function <code>wait</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Waits for the result will become available.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
error condition <code><phrase role="identifier">future_errc</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">no_state</phrase></code>
|
|
or <code><phrase role="identifier">fiber_interrupted</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="shared_future_wait_for_bridgehead">
|
|
<phrase id="shared_future_wait_for"/>
|
|
<link linkend="shared_future_wait_for">Templated
|
|
member function <code>wait_for</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Waits for the result will become available or <code><phrase role="identifier">timeout_duration</phrase></code>
|
|
has passed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Result:</term>
|
|
<listitem>
|
|
<para>
|
|
A <code><phrase role="identifier">future_status</phrase></code> is
|
|
returned indicating the reason for returning.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
error condition <code><phrase role="identifier">future_errc</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">no_state</phrase></code>
|
|
or <code><phrase role="identifier">fiber_interrupted</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="shared_future_wait_until_bridgehead">
|
|
<phrase id="shared_future_wait_until"/>
|
|
<link linkend="shared_future_wait_until">Member
|
|
function <code>wait_until</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Waits for the result will become available or <code><phrase role="identifier">timeout_time</phrase></code>
|
|
has passed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Result:</term>
|
|
<listitem>
|
|
<para>
|
|
A <code><phrase role="identifier">future_status</phrase></code> is
|
|
returned indicating the reason for returning.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
error condition <code><phrase role="identifier">future_errc</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">no_state</phrase></code>
|
|
or <code><phrase role="identifier">fiber_interrupted</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
]
|
|
</para>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fibers_async_bridgehead">
|
|
<phrase id="fibers_async"/>
|
|
<link linkend="fibers_async">Non-member function <code>fibers::async()</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">future</phrase><phrase role="special">/</phrase><phrase role="identifier">async</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="special">></phrase> <phrase role="identifier">async</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Executes <code><phrase role="identifier">fn</phrase></code> in a
|
|
fiber and returns an associated future.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Result:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future</phrase><phrase role="special"><</phrase>
|
|
<phrase role="keyword">typename</phrase> <phrase role="identifier">result_of</phrase><phrase
|
|
role="special"><</phrase> <phrase role="identifier">Fn</phrase>
|
|
<phrase role="special">>::</phrase><phrase role="identifier">type</phrase>
|
|
<phrase role="special">></phrase></code> representing the shared
|
|
state associated with the asynchronous execution of <code><phrase
|
|
role="identifier">fn</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_exception</phrase></code> or
|
|
<code><phrase role="identifier">future_error</phrase></code> if an
|
|
error occurs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<warning>
|
|
<para>
|
|
Launch policy <code><phrase role="identifier">deferred</phrase></code>,
|
|
which indicates you simply want to defer the function call until a later
|
|
time (lazy evaluation), is not supported yet.
|
|
</para>
|
|
</warning>
|
|
</section>
|
|
<section id="fiber.synchronization.futures.promise">
|
|
<title><anchor id="class_promise"/><link linkend="fiber.synchronization.futures.promise">Template
|
|
<code><phrase role="identifier">promise</phrase><phrase role="special"><></phrase></code></link></title>
|
|
<para>
|
|
A <link linkend="class_promise"> <code>promise<></code></link> provides a mechanism to store a value that
|
|
can later be accessed asynchronously by a <link linkend="class_future"> <code>future<></code></link> object.
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">promise</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Allocator</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">promise</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase><phrase role="special">,</phrase> <phrase role="identifier">Allocator</phrase> <phrase role="identifier">alloc</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="identifier">promise</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">promise</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="special">~</phrase><phrase role="identifier">promise</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">promise</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">promise</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">promise</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">operator</phrase> <phrase role="identifier">safe_bool</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">!()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="identifier">get_future</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">R</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">value</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">R</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">value</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">set_exception</phrase><phrase role="special">(</phrase> <phrase role="identifier">exception_ptr</phrase> <phrase role="identifier">p</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.promise.h0">
|
|
<phrase id="fiber.synchronization.futures.promise.default_constructor"/><link
|
|
linkend="fiber.synchronization.futures.promise.default_constructor">Default
|
|
constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">promise</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Creates a promise with an empty shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.promise.h1">
|
|
<phrase id="fiber.synchronization.futures.promise.constructor"/><link linkend="fiber.synchronization.futures.promise.constructor">Constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Allocator</phrase> <phrase role="special">></phrase>
|
|
<phrase role="identifier">promise</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase><phrase role="special">,</phrase> <phrase role="identifier">Allocator</phrase> <phrase role="identifier">alloc</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Creates a promise with an empty shared state by using <code><phrase
|
|
role="identifier">alloc</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.promise.h2">
|
|
<phrase id="fiber.synchronization.futures.promise.move_constructor"/><link
|
|
linkend="fiber.synchronization.futures.promise.move_constructor">Move constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">promise</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Creates a promise by moving the shared state from <code><phrase role="identifier">other</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postcondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">other</phrase></code> contains no
|
|
valid shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.promise.h3">
|
|
<phrase id="fiber.synchronization.futures.promise.destructor"/><link linkend="fiber.synchronization.futures.promise.destructor">Destructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="special">~</phrase><phrase role="identifier">promise</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Destroys <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
and abandons the shared state if shared state is ready; otherwise
|
|
stores <code><phrase role="identifier">future_error</phrase></code>
|
|
with error condition <code><phrase role="identifier">future_errc</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">broken_promise</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="promise_operator_assign_bridgehead">
|
|
<phrase id="promise_operator_assign"/>
|
|
<link linkend="promise_operator_assign">Member
|
|
function <code>operator=</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">promise</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Transfers the ownership of shared state to <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postcondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">other</phrase></code> contains no
|
|
valid shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="promise_swap_bridgehead">
|
|
<phrase id="promise_swap"/>
|
|
<link linkend="promise_swap">Member function <code>swap</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Swaps the shared state between other and <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="promise_operator safe_bool_bridgehead">
|
|
<phrase id="promise_operator safe_bool"/>
|
|
<link linkend="promise_operator
|
|
safe_bool">Member function <code>operator safe_bool</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">operator</phrase> <phrase role="identifier">safe_bool</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Returns <code><phrase role="keyword">true</phrase></code> if <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
contains a non-empty shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="promise_operator_not_bridgehead">
|
|
<phrase id="promise_operator_not"/>
|
|
<link linkend="promise_operator_not">Member
|
|
function <code>operator!</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">!()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Returns <code><phrase role="keyword">true</phrase></code> if <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
contains an empty shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="promise_get_future_bridgehead">
|
|
<phrase id="promise_get_future"/>
|
|
<link linkend="promise_get_future">Member
|
|
function <code>get_future</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="identifier">get_future</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
A <link linkend="class_future"> <code>future<></code></link> with the same shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
<code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">future_already_retrieved</phrase></code> or <code><phrase
|
|
role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">no_state</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="promise_set_value_bridgehead">
|
|
<phrase id="promise_set_value"/>
|
|
<link linkend="promise_set_value">Member function
|
|
<code>set_value</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">R</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">value</phrase><phrase role="special">);</phrase>
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">R</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">value</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Store the result in the shared state and marks the state as ready.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
<code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">future_already_satisfied</phrase></code> or <code><phrase
|
|
role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">no_state</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="promise_set_exception_bridgehead">
|
|
<phrase id="promise_set_exception"/>
|
|
<link linkend="promise_set_exception">Member
|
|
function <code>set_exception</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">set_exception</phrase><phrase role="special">(</phrase> <phrase role="identifier">exception_ptr</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Store an exception pointer in the shared state and marks the state
|
|
as ready.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
<code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">future_already_satisfied</phrase></code> or <code><phrase
|
|
role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">no_state</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
<section id="fiber.synchronization.futures.packaged_task">
|
|
<title><anchor id="class_packaged_task"/><link linkend="fiber.synchronization.futures.packaged_task">Template
|
|
<code><phrase role="identifier">packaged_task</phrase><phrase role="special"><></phrase></code></link></title>
|
|
<para>
|
|
A <link linkend="class_packaged_task"> <code>packaged_task<></code></link> wraps a callable target that
|
|
returns a value so that the return value can be computed asynchronously.
|
|
</para>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">R</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">packaged_task</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase><phrase role="special">(</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">...</phrase> <phrase role="special">)</phrase> <phrase role="special">></phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="identifier">packaged_task</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">explicit</phrase> <phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Allocator</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">explicit</phrase> <phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase><phrase role="special">,</phrase> <phrase role="identifier">Allocator</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">alloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="special">~</phrase><phrase role="identifier">packaged_task</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">packaged_task</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">packaged_task</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">operator</phrase> <phrase role="identifier">safe_bool</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">!()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="keyword">bool</phrase> <phrase role="identifier">valid</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="identifier">get_future</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="keyword">operator</phrase><phrase role="special">()(</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">reset</phrase><phrase role="special">();</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.packaged_task.h0">
|
|
<phrase id="fiber.synchronization.futures.packaged_task.default_constructor__code__phrase_role__identifier__packaged_task__phrase__phrase_role__special______phrase___code_"/><link
|
|
linkend="fiber.synchronization.futures.packaged_task.default_constructor__code__phrase_role__identifier__packaged_task__phrase__phrase_role__special______phrase___code_">Default
|
|
constructor <code><phrase role="identifier">packaged_task</phrase><phrase
|
|
role="special">()</phrase></code></link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">packaged_task</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Constructs an object of class <code><phrase role="identifier">packaged_task</phrase></code>
|
|
with no shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.packaged_task.h1">
|
|
<phrase id="fiber.synchronization.futures.packaged_task.templated_constructor__code__phrase_role__keyword__template__phrase__phrase_role__special___lt__gt___phrase___phrase_role__identifier__packaged_task__phrase__phrase_role__special______phrase___code_"/><link
|
|
linkend="fiber.synchronization.futures.packaged_task.templated_constructor__code__phrase_role__keyword__template__phrase__phrase_role__special___lt__gt___phrase___phrase_role__identifier__packaged_task__phrase__phrase_role__special______phrase___code_">Templated
|
|
constructor <code><phrase role="keyword">template</phrase><phrase role="special"><></phrase>
|
|
<phrase role="identifier">packaged_task</phrase><phrase role="special">()</phrase></code></link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">explicit</phrase> <phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">);</phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Allocator</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">explicit</phrase> <phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase><phrase role="special">,</phrase> <phrase role="identifier">Allocator</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">alloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Constructs an object of class <code><phrase role="identifier">packaged_task</phrase></code>
|
|
with a shared state and stores the callable target <code><phrase
|
|
role="identifier">fn</phrase></code> internally.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Note:</term>
|
|
<listitem>
|
|
<para>
|
|
The signature of <code><phrase role="identifier">Fn</phrase></code>
|
|
should have a return type convertible to <code><phrase role="identifier">R</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.packaged_task.h2">
|
|
<phrase id="fiber.synchronization.futures.packaged_task.move_constructor"/><link
|
|
linkend="fiber.synchronization.futures.packaged_task.move_constructor">Move
|
|
constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Creates a packaged_task by moving the shared state from <code><phrase
|
|
role="identifier">other</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postcondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">other</phrase></code> contains no
|
|
valid shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect5" id="fiber.synchronization.futures.packaged_task.h3">
|
|
<phrase id="fiber.synchronization.futures.packaged_task.destructor"/><link
|
|
linkend="fiber.synchronization.futures.packaged_task.destructor">Destructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="special">~</phrase><phrase role="identifier">packaged_task</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Destroys <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
and abandons the shared state if shared state is ready; otherwise
|
|
stores <code><phrase role="identifier">future_error</phrase></code>
|
|
with error condition <code><phrase role="identifier">future_errc</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">broken_promise</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="packaged_task_operator_assign_bridgehead">
|
|
<phrase id="packaged_task_operator_assign"/>
|
|
<link linkend="packaged_task_operator_assign">Member
|
|
function <code>operator=</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">packaged_task</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Transfers the ownership of shared state to <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postcondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">other</phrase></code> contains no
|
|
valid shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="packaged_task_swap_bridgehead">
|
|
<phrase id="packaged_task_swap"/>
|
|
<link linkend="packaged_task_swap">Member
|
|
function <code>swap</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Swaps the shared state between other and <code><phrase role="special">*</phrase><phrase
|
|
role="keyword">this</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="packaged_task_operator safe_bool_bridgehead">
|
|
<phrase id="packaged_task_operator safe_bool"/>
|
|
<link linkend="packaged_task_operator
|
|
safe_bool">Member function <code>operator safe_bool</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">operator</phrase> <phrase role="identifier">safe_bool</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Returns <code><phrase role="keyword">true</phrase></code> if <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
contains a non-empty shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="packaged_task_operator_not_bridgehead">
|
|
<phrase id="packaged_task_operator_not"/>
|
|
<link linkend="packaged_task_operator_not">Member
|
|
function <code>operator!</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">!()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Returns <code><phrase role="keyword">true</phrase></code> if <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
contains an empty shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="packaged_task_valid_bridgehead">
|
|
<phrase id="packaged_task_valid"/>
|
|
<link linkend="packaged_task_valid">Member
|
|
function <code>valid</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">valid</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Returns <code><phrase role="keyword">true</phrase></code> if <code><phrase
|
|
role="special">*</phrase><phrase role="keyword">this</phrase></code>
|
|
contains a shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="packaged_task_get_future_bridgehead">
|
|
<phrase id="packaged_task_get_future"/>
|
|
<link linkend="packaged_task_get_future">Member
|
|
function <code>get_future</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="identifier">get_future</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
A <link linkend="class_future"> <code>future<></code></link> with the same shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
<code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">future_already_retrieved</phrase></code> or <code><phrase
|
|
role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">no_state</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="packaged_task_operator_apply_bridgehead">
|
|
<phrase id="packaged_task_operator_apply"/>
|
|
<link linkend="packaged_task_operator_apply">Member
|
|
function <code>operator()</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="keyword">operator</phrase><phrase role="special">()(</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Invokes the stored callable target. Any exception thrown by the callable
|
|
target <code><phrase role="identifier">fn</phrase></code> is stored
|
|
in the shared state. Otherwise, the value returned by <code><phrase
|
|
role="identifier">fn</phrase></code> is stored in the shared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
<code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">no_state</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="packaged_task_reset_bridgehead">
|
|
<phrase id="packaged_task_reset"/>
|
|
<link linkend="packaged_task_reset">Member
|
|
function <code>reset</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">reset</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Resets the shared state and abondons the result of previous executions.
|
|
A new shared state is constructed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">future_error</phrase></code> with
|
|
<code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase
|
|
role="identifier">no_state</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
<section id="fiber.fls">
|
|
<title><link linkend="fiber.fls">Fiber local storage</link></title>
|
|
<bridgehead renderas="sect3" id="fiber.fls.h0">
|
|
<phrase id="fiber.fls.synopsis"/><link linkend="fiber.fls.synopsis">Synopsis</link>
|
|
</bridgehead>
|
|
<para>
|
|
Fiber local storage allows a separate instance of a given data item for each
|
|
fiber.
|
|
</para>
|
|
<bridgehead renderas="sect3" id="fiber.fls.h1">
|
|
<phrase id="fiber.fls.cleanup_at_fiber_exit"/><link linkend="fiber.fls.cleanup_at_fiber_exit">Cleanup
|
|
at fiber exit</link>
|
|
</bridgehead>
|
|
<para>
|
|
When a fiber exits, the objects associated with each <link linkend="class_fiber_specific_ptr"> <code>fiber_specific_ptr</code></link> instance
|
|
are destroyed. By default, the object pointed to by a pointer <code><phrase
|
|
role="identifier">p</phrase></code> is destroyed by invoking <code><phrase
|
|
role="keyword">delete</phrase> <phrase role="identifier">p</phrase></code>,
|
|
but this can be overridden for a specific instance of <link linkend="class_fiber_specific_ptr"> <code>fiber_specific_ptr</code></link> by
|
|
providing a cleanup routine <code><phrase role="identifier">func</phrase></code>
|
|
to the constructor. In this case, the object is destroyed by invoking <code><phrase
|
|
role="identifier">func</phrase><phrase role="special">(</phrase><phrase role="identifier">p</phrase><phrase
|
|
role="special">)</phrase></code>. The cleanup functions are called in an unspecified
|
|
order.
|
|
</para>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="class_fiber_specific_ptr_bridgehead">
|
|
<phrase id="class_fiber_specific_ptr"/>
|
|
<link linkend="class_fiber_specific_ptr">Class
|
|
<code>fiber_specific_ptr</code></link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">fss</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase>
|
|
<phrase role="keyword">class</phrase> <phrase role="identifier">fiber_specific_ptr</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="keyword">public</phrase><phrase role="special">:</phrase>
|
|
<phrase role="keyword">typedef</phrase> <phrase role="identifier">T</phrase> <phrase role="identifier">element_type</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">explicit</phrase> <phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">(</phrase> <phrase role="keyword">void</phrase><phrase role="special">(*</phrase><phrase role="identifier">fn</phrase><phrase role="special">)(</phrase><phrase role="identifier">T</phrase><phrase role="special">*)</phrase> <phrase role="special">);</phrase>
|
|
|
|
<phrase role="special">~</phrase><phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_specific_ptr</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">fiber_specific_ptr</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">fiber_specific_ptr</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">T</phrase> <phrase role="special">*</phrase> <phrase role="identifier">get</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">T</phrase> <phrase role="special">*</phrase> <phrase role="keyword">operator</phrase><phrase role="special">->()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">T</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">*()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
|
|
<phrase role="identifier">T</phrase> <phrase role="special">*</phrase> <phrase role="identifier">release</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">void</phrase> <phrase role="identifier">reset</phrase><phrase role="special">(</phrase> <phrase role="identifier">T</phrase> <phrase role="special">*</phrase> <phrase role="identifier">t</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">};</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect3" id="fiber.fls.h2">
|
|
<phrase id="fiber.fls.constructor"/><link linkend="fiber.fls.constructor">Constructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">();</phrase>
|
|
|
|
<phrase role="keyword">explicit</phrase> <phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">(</phrase> <phrase role="keyword">void</phrase><phrase role="special">(*</phrase><phrase role="identifier">fn</phrase><phrase role="special">)(</phrase><phrase role="identifier">T</phrase><phrase role="special">*)</phrase> <phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Requires:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">delete</phrase> <phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">get</phrase><phrase
|
|
role="special">()</phrase></code> is well-formed; fn(this->get())
|
|
does not throw
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Construct a <link linkend="class_fiber_specific_ptr"> <code>fiber_specific_ptr</code></link> object for storing
|
|
a pointer to an object of type <code><phrase role="identifier">T</phrase></code>
|
|
specific to each fiber. When <code><phrase role="identifier">reset</phrase><phrase
|
|
role="special">()</phrase></code> is called, or the fiber exits, <link linkend="class_fiber_specific_ptr"> <code>fiber_specific_ptr</code></link> calls
|
|
<code><phrase role="identifier">fn</phrase><phrase role="special">(</phrase><phrase
|
|
role="keyword">this</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">get</phrase><phrase role="special">())</phrase></code>.
|
|
If the no-arguments constructor is used, the default <code><phrase role="keyword">delete</phrase></code>-based
|
|
cleanup function will be used to destroy the fiber-local objects.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_resource_error</phrase></code>
|
|
if an error occurs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<bridgehead renderas="sect3" id="fiber.fls.h3">
|
|
<phrase id="fiber.fls.destructor"/><link linkend="fiber.fls.destructor">Destructor</link>
|
|
</bridgehead>
|
|
<programlisting><phrase role="special">~</phrase><phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Requires:</term>
|
|
<listitem>
|
|
<para>
|
|
All the fiber specific instances associated to this <link linkend="class_fiber_specific_ptr"> <code>fiber_specific_ptr</code></link>
|
|
(except
|
|
maybe the one associated to this fiber) must be null.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Calls <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">reset</phrase><phrase role="special">()</phrase></code>
|
|
to clean up the associated value for the current fiber, and destroys
|
|
<code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Remarks:</term>
|
|
<listitem>
|
|
<para>
|
|
The requirement is due to the fact that in order to delete all these
|
|
instances, the implementation should be forced to maintain a list of
|
|
all the fibers having an associated specific ptr, which is against the
|
|
goal of fiber specific data. In general, a <link linkend="class_fiber_specific_ptr"> <code>fiber_specific_ptr</code></link> should
|
|
outlive the fibers that use it.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<note>
|
|
<para>
|
|
Care needs to be taken to ensure that any fibers still running after an instance
|
|
of <link linkend="class_fiber_specific_ptr"> <code>fiber_specific_ptr</code></link> has been destroyed do not call
|
|
any member functions on that instance.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_specific_ptr_get_bridgehead">
|
|
<phrase id="fiber_specific_ptr_get"/>
|
|
<link linkend="fiber_specific_ptr_get">Member
|
|
function <code>get</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">T</phrase><phrase role="special">*</phrase> <phrase role="identifier">get</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
The pointer associated with the current fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<note>
|
|
<para>
|
|
The initial value associated with an instance of <link linkend="class_fiber_specific_ptr"> <code>fiber_specific_ptr</code></link> is
|
|
<code><phrase role="identifier">NULL</phrase></code> for each fiber.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_specific_ptr_operator_arrow_bridgehead">
|
|
<phrase id="fiber_specific_ptr_operator_arrow"/>
|
|
<link linkend="fiber_specific_ptr_operator_arrow">Member
|
|
function <code>operator-></code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">T</phrase><phrase role="special">*</phrase> <phrase role="keyword">operator</phrase><phrase role="special">->()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">get</phrase><phrase role="special">()</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_specific_ptr_operator_star_bridgehead">
|
|
<phrase id="fiber_specific_ptr_operator_star"/>
|
|
<link linkend="fiber_specific_ptr_operator_star">Member
|
|
function <code>operator*</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">T</phrase><phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">*()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Requires:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">get</phrase></code> is not <code><phrase role="identifier">NULL</phrase></code>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Returns:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="special">*(</phrase><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">get</phrase><phrase
|
|
role="special">())</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_specific_ptr_release_bridgehead">
|
|
<phrase id="fiber_specific_ptr_release"/>
|
|
<link linkend="fiber_specific_ptr_release">Member
|
|
function <code>release</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="identifier">T</phrase><phrase role="special">*</phrase> <phrase role="identifier">release</phrase><phrase role="special">();</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
Return <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">get</phrase><phrase role="special">()</phrase></code>
|
|
and store <code><phrase role="identifier">NULL</phrase></code> as the
|
|
pointer associated with the current fiber without invoking the cleanup
|
|
function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postcondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">get</phrase><phrase role="special">()==</phrase><phrase
|
|
role="number">0</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
Nothing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
<bridgehead renderas="sect4" id="fiber_specific_ptr_reset_bridgehead">
|
|
<phrase id="fiber_specific_ptr_reset"/>
|
|
<link linkend="fiber_specific_ptr_reset">Member
|
|
function <code>reset</code>()</link>
|
|
</bridgehead>
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">reset</phrase><phrase role="special">(</phrase><phrase role="identifier">T</phrase><phrase role="special">*</phrase> <phrase role="identifier">new_value</phrase><phrase role="special">=</phrase><phrase role="number">0</phrase><phrase role="special">);</phrase>
|
|
</programlisting>
|
|
<variablelist>
|
|
<title></title>
|
|
<varlistentry>
|
|
<term>Effects:</term>
|
|
<listitem>
|
|
<para>
|
|
If <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">get</phrase><phrase role="special">()!=</phrase><phrase
|
|
role="identifier">new_value</phrase></code> and <code><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">get</phrase><phrase
|
|
role="special">()</phrase></code> is non-<code><phrase role="identifier">NULL</phrase></code>,
|
|
invoke <code><phrase role="keyword">delete</phrase> <phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">get</phrase><phrase
|
|
role="special">()</phrase></code> or <code><phrase role="identifier">fn</phrase><phrase
|
|
role="special">(</phrase><phrase role="keyword">this</phrase><phrase
|
|
role="special">-></phrase><phrase role="identifier">get</phrase><phrase
|
|
role="special">())</phrase></code> as appropriate. Store <code><phrase
|
|
role="identifier">new_value</phrase></code> as the pointer associated
|
|
with the current fiber.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Postcondition:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase
|
|
role="identifier">get</phrase><phrase role="special">()==</phrase><phrase
|
|
role="identifier">new_value</phrase></code>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Throws:</term>
|
|
<listitem>
|
|
<para>
|
|
<code><phrase role="identifier">fiber_resource_error</phrase></code>
|
|
if an error occurs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
<section id="fiber.performance">
|
|
<title><link linkend="fiber.performance">Performance</link></title>
|
|
<para>
|
|
Performance measurements were taken using <code><phrase role="identifier">std</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase
|
|
role="special">::</phrase><phrase role="identifier">highresolution_clock</phrase></code>,
|
|
with overhead corrections. The code was compiled using the build options: variant
|
|
= release, optimization = speed <footnote id="fiber.performance.f0">
|
|
<para>
|
|
Intel Core2 Q6700, x86_64, 3GHz
|
|
</para>
|
|
</footnote>.
|
|
</para>
|
|
<table frame="all" id="fiber.performance.overhead_of_creating_and_joining">
|
|
<title>Overhead of creating and joining</title>
|
|
<tgroup cols="4">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
thread
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
fiber
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
tbb
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
qthread
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
31 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
1.1 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
570 ns
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
620 ns
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<table frame="all" id="fiber.performance.overhead_of_detach">
|
|
<title>Overhead of detach</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
thread
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
fiber
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
20 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
3.2 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<table frame="all" id="fiber.performance.overhead_of_yield">
|
|
<title>Overhead of yield</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
thread
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
fiber
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
38 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
1.3 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<table frame="all" id="fiber.performance.overhead_of_waiting_on_a_future">
|
|
<title>Overhead of waiting on a future</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
thread
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
fiber
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
32 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
3.0 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<table frame="all" id="fiber.performance.scaling_of_creating_and_joining">
|
|
<title>Scaling of creating and joining</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
average of
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
thread
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
fiber
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
10
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
50.65 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
4.83 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
50
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
52.99 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
4.84 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
100
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
50.44 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
5.24 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
500
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
45.19 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
4.86 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
1000
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
42.59 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
5.04 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
5000
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
42.30 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
5.07 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
10000
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
41.07 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
5.12 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>
|
|
Using internally atomics by applying BOOST_FIBER_NO_ATOMICS.
|
|
</para>
|
|
<table frame="all" id="fiber.performance.overhead_of_creating_and_joinin0">
|
|
<title>Overhead of creating and joining</title>
|
|
<tgroup cols="4">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
thread
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
fiber
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
tbb
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
qthread
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
31 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
955 ns
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
570 ns
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
620 ns
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<table frame="all" id="fiber.performance.overhead_of_detach0">
|
|
<title>Overhead of detach</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
thread
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
fiber
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
20 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
3.2 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<table frame="all" id="fiber.performance.overhead_of_yield0">
|
|
<title>Overhead of yield</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
thread
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
fiber
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
38 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
1.1 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<table frame="all" id="fiber.performance.overhead_of_waiting_on_a_future0">
|
|
<title>Overhead of waiting on a future</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
thread
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
fiber
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
32 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
2.4 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<table frame="all" id="fiber.performance.scaling_of_creating_and_joining0">
|
|
<title>Scaling of creating and joining</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
average of
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
thread
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
fiber
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
10
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
50.65 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
3.76 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
50
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
52.99 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
2.78 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
100
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
50.44 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
2.45 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
500
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
45.19 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
2.91 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
1000
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
42.59 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
3.60 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
5000
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
42.30 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
4.57 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
10000
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
41.07 µs
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
4.21 µs
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</section>
|
|
<section id="fiber.rational">
|
|
<title><link linkend="fiber.rational">Rational</link></title>
|
|
<bridgehead renderas="sect3" id="fiber.rational.h0">
|
|
<phrase id="fiber.rational.distinction_between_coroutines_and_fibers"/><link
|
|
linkend="fiber.rational.distinction_between_coroutines_and_fibers">distinction
|
|
between coroutines and fibers</link>
|
|
</bridgehead>
|
|
<para>
|
|
The fiber library extends the coroutine library by adding a scheduler and synchronization
|
|
mechanisms.
|
|
</para>
|
|
<programlisting><phrase role="special">*</phrase> <phrase role="identifier">a</phrase> <phrase role="identifier">coroutine</phrase> <phrase role="identifier">yields</phrase>
|
|
|
|
<phrase role="special">*</phrase> <phrase role="identifier">a</phrase> <phrase role="identifier">fiber</phrase> <phrase role="identifier">blocks</phrase>
|
|
</programlisting>
|
|
<para>
|
|
When a coroutine yields, it passes control directly to its caller (or, in the
|
|
case of symmetric coroutines, a designated other coroutine). When a fiber blocks,
|
|
it implicitly passes control to the fiber scheduler. Coroutines have no scheduler
|
|
because they need no scheduler. <footnote id="fiber.rational.f0">
|
|
<para>
|
|
<ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4024.pdf">'N4024:
|
|
Distinguishing coroutines and fibers'</ulink>
|
|
</para>
|
|
</footnote>.
|
|
</para>
|
|
<bridgehead renderas="sect3" id="fiber.rational.h1">
|
|
<phrase id="fiber.rational.what_about_transactional_memory"/><link linkend="fiber.rational.what_about_transactional_memory">what
|
|
about transactional memory</link>
|
|
</bridgehead>
|
|
<para>
|
|
GCC support transactional memory since version 4.7. Unfortunately testes showed
|
|
that transactional memory is slower (ca. 4x) than using spinlocks using atomics.
|
|
If transactional memory will be improved (supporting hybrid tm), spinlocks
|
|
will be replaced by __transaction_atomic{} statements surrounding the critical
|
|
sections.
|
|
</para>
|
|
<bridgehead renderas="sect3" id="fiber.rational.h2">
|
|
<phrase id="fiber.rational.synchronization_between_fibers_running_in_different_threads"/><link
|
|
linkend="fiber.rational.synchronization_between_fibers_running_in_different_threads">synchronization
|
|
between fibers running in different threads</link>
|
|
</bridgehead>
|
|
<para>
|
|
Synchronization classes from <ulink url="boost:/libs/thread/index.html">Boost.Thread</ulink>
|
|
do block the entire thread. In contrast to this the synchronization classes
|
|
from <emphasis role="bold">Boost.Fiber</emphasis> do block only the fiber,
|
|
so that the thread is able to schedule and run other fibers in the meantime.
|
|
The synchronization classes from <emphasis role="bold">Boost.Fiber</emphasis>
|
|
are designed to be thread-safe, e.g. it is possible to synchronize fibers running
|
|
in different schedulers (different threads) or running in the same scheduler
|
|
(same thread). (However, there is a build option to disable that support; see
|
|
<link linkend="cross_thread_sync">this description</link>.)
|
|
</para>
|
|
<bridgehead renderas="sect3" id="fiber.rational.h3">
|
|
<phrase id="fiber.rational.support_for_boost_asio"/><link linkend="fiber.rational.support_for_boost_asio">support
|
|
for Boost.Asio</link>
|
|
</bridgehead>
|
|
<para>
|
|
The support for Boost.Asio's <emphasis>async-result</emphasis> is not part
|
|
of the official API (implementation provided in example section). <emphasis>async-result</emphasis>
|
|
does not reflect that <emphasis role="bold">Boost.Fiber</emphasis> itself uses
|
|
an internal scheduler (especially fibers not in touch with code using <ulink
|
|
url="boost:/libs/asio/index.html">Boost.Asio</ulink>, for instance a sleeping
|
|
fiber will not be launched explicitly by <ulink url="boost:/libs/asio/index.html">Boost.Asio</ulink>).
|
|
The integration of <emphasis role="bold">Boost.Fiber</emphasis> into <ulink
|
|
url="boost:/libs/asio/index.html">Boost.Asio</ulink> requires some investigation
|
|
from both authors.
|
|
</para>
|
|
<bridgehead renderas="sect3" id="fiber.rational.h4">
|
|
<phrase id="fiber.rational.tested_compilers"/><link linkend="fiber.rational.tested_compilers">tested
|
|
compilers</link>
|
|
</bridgehead>
|
|
<para>
|
|
The library was tested with GCC-5.1.1, Clang-3.6.0 and MSVC-14.0 in c++14-mode.
|
|
</para>
|
|
<bridgehead renderas="sect3" id="fiber.rational.h5">
|
|
<phrase id="fiber.rational.supported_architectures"/><link linkend="fiber.rational.supported_architectures">supported
|
|
architectures</link>
|
|
</bridgehead>
|
|
<para>
|
|
<emphasis role="bold">Boost.Fiber</emphasis> depends on <ulink url="boost:/libs/context/index.html">Boost.Context</ulink>
|
|
- the list of supported architectures can be found <ulink url="boost:/libs/context/doc/html/context/architectures.html">here</ulink>.
|
|
</para>
|
|
<bridgehead renderas="sect3" id="fiber.rational.h6">
|
|
<phrase id="fiber.rational.migrating_fibers_between_threads"/><link linkend="fiber.rational.migrating_fibers_between_threads">migrating
|
|
fibers between threads</link>
|
|
</bridgehead>
|
|
<para>
|
|
The support for migrating fibers between threads was removed. Especially in
|
|
the case of NUMA-architectures it is not always advised to migrate data between
|
|
threads. Suppose fiber <emphasis>f</emphasis> is running on logical CPU <emphasis>cpu0</emphasis>
|
|
which belongs to NUMA node <emphasis>node0</emphasis>. The data of <emphasis>f</emphasis>
|
|
are allocated on the physical memory located at <emphasis>node0</emphasis>.
|
|
Migrating the fiber from <emphasis>cpu0</emphasis> to another logical CPU
|
|
<emphasis>cpuX</emphasis> which is part of NUMA node <emphasis>nodeX</emphasis>
|
|
will reduce the performance of the application because of increased latency
|
|
of memory access.
|
|
</para>
|
|
</section>
|
|
<section id="fiber.custom">
|
|
<title><anchor id="custom"/><link linkend="fiber.custom">Customization</link></title>
|
|
<para>
|
|
<emphasis role="bold">Boost.Fiber</emphasis> allows to customize the scheduling
|
|
algorithm by a user-defined implementation. A fiber-scheduler must implement
|
|
interface <link linkend="class_sched_algorithm"> <code>sched_algorithm</code></link>. <emphasis role="bold">Boost.Fiber</emphasis>
|
|
provides scheduler <link linkend="class_round_robin"> <code>round_robin</code></link>.
|
|
</para>
|
|
<programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">thread_fn</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase>
|
|
<phrase role="identifier">my_fiber_scheduler</phrase> <phrase role="identifier">mfs</phrase><phrase role="special">;</phrase>
|
|
<phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">set_scheduling_algorithm</phrase><phrase role="special">(</phrase> <phrase role="special">&</phrase> <phrase role="identifier">mfs</phrase><phrase role="special">);</phrase>
|
|
<phrase role="special">...</phrase>
|
|
<phrase role="special">}</phrase>
|
|
</programlisting>
|
|
<bridgehead renderas="sect3" id="fiber.custom.h0">
|
|
<phrase id="fiber.custom.fiber_context"/><link linkend="fiber.custom.fiber_context">fiber_context</link>
|
|
</bridgehead>
|
|
<para>
|
|
The fiber_context class is mostly supposed to be opaque. However, certain members
|
|
are available for use by a custom scheduling algorithm.
|
|
</para>
|
|
</section>
|
|
<section id="fiber.acknowledgements">
|
|
<title><link linkend="fiber.acknowledgements">Acknowledgments</link></title>
|
|
<para>
|
|
I'd like to thank Eugene Yakubovich and especially Nat Goodspeed.
|
|
</para>
|
|
</section>
|
|
</library>
|