c6a21af2ff
2010-07-22 Benjamin Kosnik <bkoz@redhat.com> DocBook 4.5 to 5.0 transition. * doc/xml/authors.xml: Update markup to DocBook 5.0. * doc/xml/faq.xml: Same. * doc/xml/api.xml: Same. * doc/xml/class.txml * doc/xml/gnu/gpl-3.0.xml: Same. * doc/xml/gnu/fdl-1.2.xml: Same. * doc/xml/gnu/fdl-1.3.xml: Same. * doc/xml/gnu/gpl-2.0.xml: Same. * doc/xml/chapter.txml: Same. * doc/xml/manual/mt_allocator.xml: Same. * doc/xml/manual/allocator.xml: Same. * doc/xml/manual/ctype.xml: Same. * doc/xml/manual/numerics.xml: Same. * doc/xml/manual/codecvt.xml: Same. * doc/xml/manual/backwards_compatibility.xml: Same. * doc/xml/manual/concurrency.xml: Same. * doc/xml/manual/intro.xml: Same. * doc/xml/manual/abi.xml: Same. * doc/xml/manual/shared_ptr.xml: Same. * doc/xml/manual/status_cxxtr1.xml: Same. * doc/xml/manual/auto_ptr.xml: Same. * doc/xml/manual/internals.xml: Same. * doc/xml/manual/atomics.xml: Same. * doc/xml/manual/parallel_mode.xml: Same. * doc/xml/manual/status_cxx1998.xml: Same. * doc/xml/manual/profile_mode.xml: Same. * doc/xml/manual/containers.xml: Same. * doc/xml/manual/io.xml: Same. * doc/xml/manual/concurrency_extensions.xml: Same. * doc/xml/manual/appendix_porting.xml: Same. * doc/xml/manual/utilities.xml: Same. * doc/xml/manual/support.xml: Same. * doc/xml/manual/bitmap_allocator.xml: Same. * doc/xml/manual/configure.xml: Same. * doc/xml/manual/build_hacking.xml: Same. * doc/xml/manual/evolution.xml: Same. * doc/xml/manual/using.xml: Same. * doc/xml/manual/using_exceptions.xml: Same. * doc/xml/manual/debug.xml: Same. * doc/xml/manual/localization.xml: Same. * doc/xml/manual/strings.xml: Same. * doc/xml/manual/debug_mode.xml: Same. * doc/xml/manual/locale.xml: Same. * doc/xml/manual/extensions.xml: Same. * doc/xml/manual/appendix_contributing.xml: Same. * doc/xml/manual/prerequisites.xml: Same. * doc/xml/manual/messages.xml: Same. * doc/xml/manual/diagnostics.xml: Same. * doc/xml/manual/algorithms.xml: Same. * doc/xml/manual/appendix_free.xml: Same. * doc/xml/manual/iterators.xml: Same. * doc/xml/manual/spine.xml: Same. * doc/xml/manual/status_cxxtr24733.xml: Same. * doc/xml/manual/status_cxx200x.xml: Same. * doc/xml/manual/test.xml: Same. * doc/xml/book.txml: Same. * doc/xml/spine.xml: Same. * doc/Makefile.am: Same. * doc/Makefile.in: Regenerate. From-SVN: r162433
334 lines
9.7 KiB
XML
334 lines
9.7 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
|
|
xml:id="manual.ext.concurrency" xreflabel="Concurrency Extensions">
|
|
<?dbhtml filename="ext_concurrency.html"?>
|
|
|
|
<info><title>Concurrency</title>
|
|
<keywordset>
|
|
<keyword>
|
|
ISO C++
|
|
</keyword>
|
|
<keyword>
|
|
library
|
|
</keyword>
|
|
</keywordset>
|
|
</info>
|
|
|
|
|
|
|
|
<section xml:id="manual.ext.concurrency.design" xreflabel="Design"><info><title>Design</title></info>
|
|
|
|
|
|
<section xml:id="manual.ext.concurrency.design.threads" xreflabel="Threads API"><info><title>Interface to Locks and Mutexes</title></info>
|
|
|
|
|
|
<para>The file <ext/concurrence.h> contains all the higher-level
|
|
constructs for playing with threads. In contrast to the atomics layer,
|
|
the concurrence layer consists largely of types. All types are defined within <code>namespace __gnu_cxx</code>.
|
|
</para>
|
|
|
|
<para>
|
|
These types can be used in a portable manner, regardless of the
|
|
specific environment. They are carefully designed to provide optimum
|
|
efficiency and speed, abstracting out underlying thread calls and
|
|
accesses when compiling for single-threaded situations (even on hosts
|
|
that support multiple threads.)
|
|
</para>
|
|
|
|
<para>The enumerated type <code>_Lock_policy</code> details the set of
|
|
available locking
|
|
policies: <code>_S_single</code>, <code>_S_mutex</code>,
|
|
and <code>_S_atomic</code>.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><code>_S_single</code></para>
|
|
<para>Indicates single-threaded code that does not need locking.
|
|
</para>
|
|
|
|
</listitem>
|
|
<listitem><para><code>_S_mutex</code></para>
|
|
<para>Indicates multi-threaded code using thread-layer abstractions.
|
|
</para>
|
|
</listitem>
|
|
<listitem><para><code>_S_atomic</code></para>
|
|
<para>Indicates multi-threaded code using atomic operations.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>The compile-time constant <code>__default_lock_policy</code> is set
|
|
to one of the three values above, depending on characteristics of the
|
|
host environment and the current compilation flags.
|
|
</para>
|
|
|
|
<para>Two more datatypes make up the rest of the
|
|
interface: <code>__mutex</code>, and <code>__scoped_lock</code>.
|
|
</para>
|
|
|
|
<para>
|
|
</para>
|
|
|
|
<para>The scoped lock idiom is well-discussed within the C++
|
|
community. This version takes a <code>__mutex</code> reference, and
|
|
locks it during construction of <code>__scoped_locke</code> and
|
|
unlocks it during destruction. This is an efficient way of locking
|
|
critical sections, while retaining exception-safety.
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="manual.ext.concurrency.design.atomics" xreflabel="Atomic API"><info><title>Interface to Atomic Functions</title></info>
|
|
|
|
|
|
|
|
<para>
|
|
Two functions and one type form the base of atomic support.
|
|
</para>
|
|
|
|
|
|
<para>The type <code>_Atomic_word</code> is a signed integral type
|
|
supporting atomic operations.
|
|
</para>
|
|
|
|
<para>
|
|
The two functions functions are:
|
|
</para>
|
|
|
|
<programlisting>
|
|
_Atomic_word
|
|
__exchange_and_add_dispatch(volatile _Atomic_word*, int);
|
|
|
|
void
|
|
__atomic_add_dispatch(volatile _Atomic_word*, int);
|
|
</programlisting>
|
|
|
|
<para>Both of these functions are declared in the header file
|
|
<ext/atomicity.h>, and are in <code>namespace __gnu_cxx</code>.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<code>
|
|
__exchange_and_add_dispatch
|
|
</code>
|
|
</para>
|
|
<para>Adds the second argument's value to the first argument. Returns the old value.
|
|
</para>
|
|
</listitem>
|
|
<listitem><para>
|
|
<code>
|
|
__atomic_add_dispatch
|
|
</code>
|
|
</para>
|
|
<para>Adds the second argument's value to the first argument. Has no return value.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
These functions forward to one of several specialized helper
|
|
functions, depending on the circumstances. For instance,
|
|
</para>
|
|
|
|
<para>
|
|
<code>
|
|
__exchange_and_add_dispatch
|
|
</code>
|
|
</para>
|
|
|
|
<para>
|
|
Calls through to either of:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><code>__exchange_and_add</code>
|
|
</para>
|
|
<para>Multi-thread version. Inlined if compiler-generated builtin atomics
|
|
can be used, otherwise resolved at link time to a non-builtin code
|
|
sequence.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem><para><code>__exchange_and_add_single</code>
|
|
</para>
|
|
<para>Single threaded version. Inlined.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>However, only <code>__exchange_and_add_dispatch</code>
|
|
and <code>__atomic_add_dispatch</code> should be used. These functions
|
|
can be used in a portable manner, regardless of the specific
|
|
environment. They are carefully designed to provide optimum efficiency
|
|
and speed, abstracting out atomic accesses when they are not required
|
|
(even on hosts that support compiler intrinsics for atomic
|
|
operations.)
|
|
</para>
|
|
|
|
<para>
|
|
In addition, there are two macros
|
|
</para>
|
|
|
|
<para>
|
|
<code>
|
|
_GLIBCXX_READ_MEM_BARRIER
|
|
</code>
|
|
</para>
|
|
<para>
|
|
<code>
|
|
_GLIBCXX_WRITE_MEM_BARRIER
|
|
</code>
|
|
</para>
|
|
|
|
<para>
|
|
Which expand to the appropriate write and read barrier required by the
|
|
host hardware and operating system.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
|
<section xml:id="manual.ext.concurrency.impl" xreflabel="Implementation"><info><title>Implementation</title></info>
|
|
|
|
<section xml:id="manual.ext.concurrency.impl.atomic_fallbacks" xreflabel="Atomic F"><info><title>Using Builtin Atomic Functions</title></info>
|
|
|
|
|
|
<para>The functions for atomic operations described above are either
|
|
implemented via compiler intrinsics (if the underlying host is
|
|
capable) or by library fallbacks.</para>
|
|
|
|
<para>Compiler intrinsics (builtins) are always preferred. However, as
|
|
the compiler builtins for atomics are not universally implemented,
|
|
using them directly is problematic, and can result in undefined
|
|
function calls. (An example of an undefined symbol from the use
|
|
of <code>__sync_fetch_and_add</code> on an unsupported host is a
|
|
missing reference to <code>__sync_fetch_and_add_4</code>.)
|
|
</para>
|
|
|
|
<para>In addition, on some hosts the compiler intrinsics are enabled
|
|
conditionally, via the <code>-march</code> command line flag. This makes
|
|
usage vary depending on the target hardware and the flags used during
|
|
compile.
|
|
</para>
|
|
|
|
<para>
|
|
If builtins are possible for bool-sized integral types,
|
|
<code>_GLIBCXX_ATOMIC_BUILTINS_1</code> will be defined.
|
|
If builtins are possible for int-sized integral types,
|
|
<code>_GLIBCXX_ATOMIC_BUILTINS_4</code> will be defined.
|
|
</para>
|
|
|
|
|
|
<para>For the following hosts, intrinsics are enabled by default.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>alpha</para></listitem>
|
|
<listitem><para>ia64</para></listitem>
|
|
<listitem><para>powerpc</para></listitem>
|
|
<listitem><para>s390</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>For others, some form of <code>-march</code> may work. On
|
|
non-ancient x86 hardware, <code>-march=native</code> usually does the
|
|
trick.</para>
|
|
|
|
<para> For hosts without compiler intrinsics, but with capable
|
|
hardware, hand-crafted assembly is selected. This is the case for the following hosts:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>cris</para></listitem>
|
|
<listitem><para>hppa</para></listitem>
|
|
<listitem><para>i386</para></listitem>
|
|
<listitem><para>i486</para></listitem>
|
|
<listitem><para>m48k</para></listitem>
|
|
<listitem><para>mips</para></listitem>
|
|
<listitem><para>sparc</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>And for the rest, a simulated atomic lock via pthreads.
|
|
</para>
|
|
|
|
<para> Detailed information about compiler intrinsics for atomic operations can be found in the GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html"> documentation</link>.
|
|
</para>
|
|
|
|
<para> More details on the library fallbacks from the porting <link linkend="internals.thread_safety">section</link>.
|
|
</para>
|
|
|
|
|
|
</section>
|
|
<section xml:id="manual.ext.concurrency.impl.thread" xreflabel="Pthread"><info><title>Thread Abstraction</title></info>
|
|
|
|
|
|
<para>A thin layer above IEEE 1003.1 (i.e. pthreads) is used to abstract
|
|
the thread interface for GCC. This layer is called "gthread," and is
|
|
comprised of one header file that wraps the host's default thread layer with
|
|
a POSIX-like interface.
|
|
</para>
|
|
|
|
<para> The file <gthr-default.h> points to the deduced wrapper for
|
|
the current host. In libstdc++ implementation files,
|
|
<bits/gthr.h> is used to select the proper gthreads file.
|
|
</para>
|
|
|
|
<para>Within libstdc++ sources, all calls to underlying thread functionality
|
|
use this layer. More detail as to the specific interface can be found in the source <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00883_source.html">documentation</link>.
|
|
</para>
|
|
|
|
<para>By design, the gthread layer is interoperable with the types,
|
|
functions, and usage found in the usual <pthread.h> file,
|
|
including <code>pthread_t</code>, <code>pthread_once_t</code>, <code>pthread_create</code>,
|
|
etc.
|
|
</para>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="manual.ext.concurrency.use" xreflabel="Use"><info><title>Use</title></info>
|
|
|
|
|
|
|
|
<para>Typical usage of the last two constructs is demonstrated as follows:
|
|
</para>
|
|
|
|
<programlisting>
|
|
#include <ext/concurrence.h>
|
|
|
|
namespace
|
|
{
|
|
__gnu_cxx::__mutex safe_base_mutex;
|
|
} // anonymous namespace
|
|
|
|
namespace other
|
|
{
|
|
void
|
|
foo()
|
|
{
|
|
__gnu_cxx::__scoped_lock sentry(safe_base_mutex);
|
|
for (int i = 0; i < max; ++i)
|
|
{
|
|
_Safe_iterator_base* __old = __iter;
|
|
__iter = __iter-<_M_next;
|
|
__old-<_M_detach_single();
|
|
}
|
|
}
|
|
</programlisting>
|
|
|
|
<para>In this sample code, an anonymous namespace is used to keep
|
|
the <code>__mutex</code> private to the compilation unit,
|
|
and <code>__scoped_lock</code> is used to guard access to the critical
|
|
section within the for loop, locking the mutex on creation and freeing
|
|
the mutex as control moves out of this block.
|
|
</para>
|
|
|
|
<para>Several exception classes are used to keep track of
|
|
concurrence-related errors. These classes
|
|
are: <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__concurrence_wait_error</code>,
|
|
and <code>__concurrence_broadcast_error</code>.
|
|
</para>
|
|
|
|
|
|
</section>
|
|
|
|
</chapter>
|