OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-stable/] [gcc-4.5.1/] [libstdc++-v3/] [doc/] [html/] [manual/] [using_concurrency.html] - Blame information for rev 841

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 424 jeremybenn 
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Concurrency</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_dynamic_or_shared.html" title="Linking" /><link rel="next" href="using_exceptions.html" title="Exceptions" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Concurrency</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_dynamic_or_shared.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_exceptions.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Concurrency"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.concurrency"></a>Concurrency</h2></div></div></div><p>This section discusses issues surrounding the proper compilation
4 
      of multithreaded applications which use the Standard C++
5 
      library.  This information is GCC-specific since the C++
6 
      standard does not address matters of multithreaded applications.
7 
   </p><div class="sect2" title="Prerequisites"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.prereq"></a>Prerequisites</h3></div></div></div><p>All normal disclaimers aside, multithreaded C++ application are
8 
      only supported when libstdc++ and all user code was built with
9 
      compilers which report (via <code class="code"> gcc/g++ -v </code>) the same thread
10 
      model and that model is not <span class="emphasis"><em>single</em></span>.  As long as your
11 
      final application is actually single-threaded, then it should be
12 
      safe to mix user code built with a thread model of
13 
      <span class="emphasis"><em>single</em></span> with a libstdc++ and other C++ libraries built
14 
      with another thread model useful on the platform.  Other mixes
15 
      may or may not work but are not considered supported.  (Thus, if
16 
      you distribute a shared C++ library in binary form only, it may
17 
      be best to compile it with a GCC configured with
18 
      --enable-threads for maximal interchangeability and usefulness
19 
      with a user population that may have built GCC with either
20 
      --enable-threads or --disable-threads.)
21 
   </p><p>When you link a multithreaded application, you will probably
22 
      need to add a library or flag to g++.  This is a very
23 
      non-standardized area of GCC across ports.  Some ports support a
24 
      special flag (the spelling isn't even standardized yet) to add
25 
      all required macros to a compilation (if any such flags are
26 
      required then you must provide the flag for all compilations not
27 
      just linking) and link-library additions and/or replacements at
28 
      link time.  The documentation is weak.  Here is a quick summary
29 
      to display how ad hoc this is: On Solaris, both -pthreads and
30 
      -threads (with subtly different meanings) are honored.  On OSF,
31 
      -pthread and -threads (with subtly different meanings) are
32 
      honored.  On Linux/i386, -pthread is honored.  On FreeBSD,
33 
      -pthread is honored.  Some other ports use other switches.
34 
      AFAIK, none of this is properly documented anywhere other than
35 
      in ``gcc -dumpspecs'' (look at lib and cpp entries).
36 
   </p></div><div class="sect2" title="Thread Safety"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.thread_safety"></a>Thread Safety</h3></div></div></div><p>
37 
We currently use the <a class="ulink" href="http://www.sgi.com/tech/stl/thread_safety.html" target="_top">SGI STL</a> definition of thread safety.
38 
</p><p>The library strives to be thread-safe when all of the following
39 
         conditions are met:
40 
      </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The system's libc is itself thread-safe,
41 
       </p></li><li class="listitem"><p>
42 
           The compiler in use reports a thread model other than
43 
           'single'. This can be tested via output from <code class="code">gcc
44 
           -v</code>. Multi-thread capable versions of gcc output
45 
           something like this:
46 
         </p><pre class="programlisting">
47 
%gcc -v
48 
Using built-in specs.
49 
...
50 
Thread model: posix
51 
gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
52 
</pre><p>Look for "Thread model" lines that aren't equal to "single."</p></li><li class="listitem"><p>
53 
         Requisite command-line flags are used for atomic operations
54 
         and threading. Examples of this include <code class="code">-pthread</code>
55 
         and <code class="code">-march=native</code>, although specifics vary
56 
         depending on the host environment. See <a class="ulink" href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html" target="_top">Machine
57 
         Dependent Options</a>.
58 
       </p></li><li class="listitem"><p>
59 
           An implementation of atomicity.h functions
60 
           exists for the architecture in question. See the internals documentation for more <a class="link" href="internals.html#internals.thread_safety" title="Thread Safety">details</a>.
61 
       </p></li></ul></div><p>The user-code must guard against concurrent method calls which may
62 
         access any particular library object's state.  Typically, the
63 
         application programmer may infer what object locks must be held
64 
         based on the objects referenced in a method call.  Without getting
65 
         into great detail, here is an example which requires user-level
66 
         locks:
67 
      </p><pre class="programlisting">
68 
     library_class_a shared_object_a;
69 
 
70 
     thread_main () {
71 
       library_class_b *object_b = new library_class_b;
72 
       shared_object_a.add_b (object_b);   // must hold lock for shared_object_a
73 
       shared_object_a.mutate ();          // must hold lock for shared_object_a
74 
     }
75 
 
76 
     // Multiple copies of thread_main() are started in independent threads.</pre><p>Under the assumption that object_a and object_b are never exposed to
77 
         another thread, here is an example that should not require any
78 
         user-level locks:
79 
      </p><pre class="programlisting">
80 
     thread_main () {
81 
       library_class_a object_a;
82 
       library_class_b *object_b = new library_class_b;
83 
       object_a.add_b (object_b);
84 
       object_a.mutate ();
85 
     } </pre><p>All library objects are safe to use in a multithreaded program as
86 
         long as each thread carefully locks out access by any other
87 
         thread while it uses any object visible to another thread, i.e.,
88 
         treat library objects like any other shared resource.  In general,
89 
         this requirement includes both read and write access to objects;
90 
         unless otherwise documented as safe, do not assume that two threads
91 
         may access a shared standard library object at the same time.
92 
      </p></div><div class="sect2" title="Atomics"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.atomics"></a>Atomics</h3></div></div></div><p>
93 
    </p></div><div class="sect2" title="IO"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.io"></a>IO</h3></div></div></div><p>This gets a bit tricky.  Please read carefully, and bear with me.
94 
   </p><div class="sect3" title="Structure"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.structure"></a>Structure</h4></div></div></div><p>A wrapper
95 
      type called <code class="code">__basic_file</code> provides our abstraction layer
96 
      for the <code class="code">std::filebuf</code> classes.  Nearly all decisions dealing
97 
      with actual input and output must be made in <code class="code">__basic_file</code>.
98 
   </p><p>A generic locking mechanism is somewhat in place at the filebuf layer,
99 
      but is not used in the current code.  Providing locking at any higher
100 
      level is akin to providing locking within containers, and is not done
101 
      for the same reasons (see the links above).
102 
   </p></div><div class="sect3" title="Defaults"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.defaults"></a>Defaults</h4></div></div></div><p>The __basic_file type is simply a collection of small wrappers around
103 
      the C stdio layer (again, see the link under Structure).  We do no
104 
      locking ourselves, but simply pass through to calls to <code class="code">fopen</code>,
105 
      <code class="code">fwrite</code>, and so forth.
106 
   </p><p>So, for 3.0, the question of "is multithreading safe for I/O"
107 
      must be answered with, "is your platform's C library threadsafe
108 
      for I/O?"  Some are by default, some are not; many offer multiple
109 
      implementations of the C library with varying tradeoffs of threadsafety
110 
      and efficiency.  You, the programmer, are always required to take care
111 
      with multiple threads.
112 
   </p><p>(As an example, the POSIX standard requires that C stdio FILE*
113 
       operations are atomic.  POSIX-conforming C libraries (e.g, on Solaris
114 
       and GNU/Linux) have an internal mutex to serialize operations on
115 
       FILE*s.  However, you still need to not do stupid things like calling
116 
       <code class="code">fclose(fs)</code> in one thread followed by an access of
117 
       <code class="code">fs</code> in another.)
118 
   </p><p>So, if your platform's C library is threadsafe, then your
119 
      <code class="code">fstream</code> I/O operations will be threadsafe at the lowest
120 
      level.  For higher-level operations, such as manipulating the data
121 
      contained in the stream formatting classes (e.g., setting up callbacks
122 
      inside an <code class="code">std::ofstream</code>), you need to guard such accesses
123 
      like any other critical shared resource.
124 
   </p></div><div class="sect3" title="Future"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.future"></a>Future</h4></div></div></div><p> A
125 
      second choice may be available for I/O implementations:  libio.  This is
126 
      disabled by default, and in fact will not currently work due to other
127 
      issues.  It will be revisited, however.
128 
   </p><p>The libio code is a subset of the guts of the GNU libc (glibc) I/O
129 
      implementation.  When libio is in use, the <code class="code">__basic_file</code>
130 
      type is basically derived from FILE.  (The real situation is more
131 
      complex than that... it's derived from an internal type used to
132 
      implement FILE.  See libio/libioP.h to see scary things done with
133 
      vtbls.)  The result is that there is no "layer" of C stdio
134 
      to go through; the filebuf makes calls directly into the same
135 
      functions used to implement <code class="code">fread</code>, <code class="code">fwrite</code>,
136 
      and so forth, using internal data structures.  (And when I say
137 
      "makes calls directly," I mean the function is literally
138 
      replaced by a jump into an internal function.  Fast but frightening.
139 
      *grin*)
140 
   </p><p>Also, the libio internal locks are used.  This requires pulling in
141 
      large chunks of glibc, such as a pthreads implementation, and is one
142 
      of the issues preventing widespread use of libio as the libstdc++
143 
      cstdio implementation.
144 
   </p><p>But we plan to make this work, at least as an option if not a future
145 
      default.  Platforms running a copy of glibc with a recent-enough
146 
      version will see calls from libstdc++ directly into the glibc already
147 
      installed.  For other platforms, a copy of the libio subsection will
148 
      be built and included in libstdc++.
149 
   </p></div><div class="sect3" title="Alternatives"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.alt"></a>Alternatives</h4></div></div></div><p>Don't forget that other cstdio implementations are possible.  You could
150 
      easily write one to perform your own forms of locking, to solve your
151 
      "interesting" problems.
152 
   </p></div></div><div class="sect2" title="Containers"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.containers"></a>Containers</h3></div></div></div><p>This section discusses issues surrounding the design of
153 
      multithreaded applications which use Standard C++ containers.
154 
      All information in this section is current as of the gcc 3.0
155 
      release and all later point releases.  Although earlier gcc
156 
      releases had a different approach to threading configuration and
157 
      proper compilation, the basic code design rules presented here
158 
      were similar.  For information on all other aspects of
159 
      multithreading as it relates to libstdc++, including details on
160 
      the proper compilation of threaded code (and compatibility between
161 
      threaded and non-threaded code), see Chapter 17.
162 
   </p><p>Two excellent pages to read when working with the Standard C++
163 
      containers and threads are
164 
      <a class="ulink" href="http://www.sgi.com/tech/stl/thread_safety.html" target="_top">SGI's
165 
      http://www.sgi.com/tech/stl/thread_safety.html</a> and
166 
      <a class="ulink" href="http://www.sgi.com/tech/stl/Allocators.html" target="_top">SGI's
167 
      http://www.sgi.com/tech/stl/Allocators.html</a>.
168 
   </p><p><span class="emphasis"><em>However, please ignore all discussions about the user-level
169 
      configuration of the lock implementation inside the STL
170 
      container-memory allocator on those pages.  For the sake of this
171 
      discussion, libstdc++ configures the SGI STL implementation,
172 
      not you.  This is quite different from how gcc pre-3.0 worked.
173 
      In particular, past advice was for people using g++ to
174 
      explicitly define _PTHREADS or other macros or port-specific
175 
      compilation options on the command line to get a thread-safe
176 
      STL.  This is no longer required for any port and should no
177 
      longer be done unless you really know what you are doing and
178 
      assume all responsibility.</em></span>
179 
   </p><p>Since the container implementation of libstdc++ uses the SGI
180 
      code, we use the same definition of thread safety as SGI when
181 
      discussing design.  A key point that beginners may miss is the
182 
      fourth major paragraph of the first page mentioned above
183 
      (<span class="emphasis"><em>For most clients...</em></span>), which points out that
184 
      locking must nearly always be done outside the container, by
185 
      client code (that'd be you, not us).  There is a notable
186 
      exceptions to this rule.  Allocators called while a container or
187 
      element is constructed uses an internal lock obtained and
188 
      released solely within libstdc++ code (in fact, this is the
189 
      reason STL requires any knowledge of the thread configuration).
190 
   </p><p>For implementing a container which does its own locking, it is
191 
      trivial to provide a wrapper class which obtains the lock (as
192 
      SGI suggests), performs the container operation, and then
193 
      releases the lock.  This could be templatized <span class="emphasis"><em>to a certain
194 
      extent</em></span>, on the underlying container and/or a locking
195 
      mechanism.  Trying to provide a catch-all general template
196 
      solution would probably be more trouble than it's worth.
197 
   </p><p>The library implementation may be configured to use the
198 
      high-speed caching memory allocator, which complicates thread
199 
      safety issues. For all details about how to globally override
200 
      this at application run-time
201 
      see <a class="link" href="using_macros.html" title="Macros">here</a>. Also
202 
      useful are details
203 
      on <a class="link" href="memory.html#manual.util.memory.allocator" title="Allocators">allocator</a>
204 
      options and capabilities.
205 
   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_dynamic_or_shared.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_exceptions.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Linking </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Exceptions</td></tr></table></div></body></html>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.