[gcc] GCC 4.5.0=>4.5.1

gcc/libstdc++-v3/doc/xml/manual/concurrency.xml

Index: gcc/libstdc++-v3/doc/xml/manual/concurrency.xml
diff --git a/gcc/libstdc++-v3/doc/xml/manual/concurrency.xml b/gcc/libstdc++-v3/doc/xml/manual/concurrency.xml
deleted file mode 100644
index 2a676eda3e1ed8f521edd730ccd7b09d4d4cb6c9..0000000000000000000000000000000000000000
--- a/gcc/libstdc++-v3/doc/xml/manual/concurrency.xml
+++ /dev/null
@@ -1,337 +0,0 @@
-<?xml version='1.0'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" 
-[ ]>
-
-<chapter id="manual.ext.concurrency" xreflabel="Concurrency Extensions">
-<?dbhtml filename="ext_concurrency.html"?>
-
-<chapterinfo>
-  <keywordset>
-    <keyword>
-      ISO C++
-    </keyword>
-    <keyword>
-      library
-    </keyword>
-  </keywordset>
-</chapterinfo>
-
-<title>Concurrency</title>
-
-<sect1 id="manual.ext.concurrency.design" xreflabel="Design">
-  <title>Design</title>
-
-  <sect2 id="manual.ext.concurrency.design.threads" xreflabel="Threads API">
-    <title>Interface to Locks and Mutexes</title>
-
-<para>The file &lt;ext/concurrence.h&gt; 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>
-  </sect2>
-
-  <sect2 id="manual.ext.concurrency.design.atomics" xreflabel="Atomic API">
-    <title>Interface to Atomic Functions</title>
-
-
-<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
-&lt;ext/atomicity.h&gt;, 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>
-  </sect2>
-
-</sect1>
-
-
-<sect1 id="manual.ext.concurrency.impl" xreflabel="Implementation">
-  <title>Implementation</title>
-  <sect2 id="manual.ext.concurrency.impl.atomic_fallbacks" xreflabel="Atomic F">
-    <title>Using Builtin Atomic Functions</title>
-    
-<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 <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html"> documentation</ulink>.
-</para>
-
-<para> More details on the library fallbacks from the porting <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/porting.html#Thread%20safety">section</ulink>.
-</para>
-
-
-  </sect2>
-  <sect2 id="manual.ext.concurrency.impl.thread" xreflabel="Pthread">
-    <title>Thread Abstraction</title>
-
-<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 &lt;gthr-default.h&gt; points to the deduced wrapper for
-the current host. In libstdc++ implementation files,
-&lt;bits/gthr.h&gt; 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 <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/gthr_8h-source.html">documentation</ulink>.
-</para>
-
-<para>By design, the gthread layer is interoperable with the types,
-functions, and usage found in the usual &lt;pthread.h&gt; file,
-including <code>pthread_t</code>, <code>pthread_once_t</code>, <code>pthread_create</code>,
-etc.
-</para>
-
-  </sect2>  
-</sect1>
-
-<sect1 id="manual.ext.concurrency.use" xreflabel="Use">
-
-  <title>Use</title>
-
-<para>Typical usage of the last two constructs is demonstrated as follows:
-</para>
-
-<programlisting>
-#include &lt;ext/concurrence.h&gt;
-
-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 &lt; max;  ++i)
-      {
-	_Safe_iterator_base* __old = __iter;
-	__iter = __iter-&lt;_M_next;
-	__old-&lt;_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>
-
-
-</sect1>
-
-</chapter>