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

Subversion Repositories scarts

[/] [scarts/] [trunk/] [toolchain/] [scarts-gcc/] [gcc-4.1.1/] [libstdc++-v3/] [docs/] [html/] [17_intro/] [howto.html] - Blame information for rev 20

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 20 jlechner 
<?xml version="1.0" encoding="ISO-8859-1"?>
2 
<!DOCTYPE html
3 
          PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4 
          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5 
 
6 
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7 
<head>
8 
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
9 
   <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
10 
   <meta name="KEYWORDS" content="HOWTO, libstdc++, gcc, g++, libg++, STL" />
11 
   <meta name="DESCRIPTION" content="HOWTO for libstdc++ chapter 17." />
12 
   <meta name="GENERATOR" content="vi and eight fingers" />
13 
   <title>libstdc++-v3 HOWTO:  Chapter 17: Library Introduction</title>
14 
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
15 
<link rel="Start" href="../documentation.html" type="text/html"
16 
 title="GNU C++ Standard Library" />
17 
<link rel="Next" href="../18_support/howto.html" type="text/html"
18 
  title="Library Support" />
19 
<link rel="Copyright" href="license.html" type="text/html" />
20 
<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
21 
</head>
22 
<body>
23 
 
24 
<h1 class="centered"><a name="top">Chapter 17:  Library Introduction</a></h1>
25 
 
26 
<p>Chapter 17 is actually a list of definitions and descriptions used
27 
   in the following chapters of the Standard when describing the actual
28 
   library.  Here, we use &quot;Introduction&quot; as an introduction
29 
   to the <em>GNU implementation of</em> the ISO Standard C++ Library.
30 
</p>
31 
 
32 
 
33 
<!-- ####################################################### -->
34 
<hr />
35 
<h1>Contents</h1>
36 
<ul>
37 
   <li><a href="#2">The Standard C++ header files</a></li>
38 
   <li><a href="#3">The Standard C++ library and multithreading</a></li>
39 
   <li><a href="#4"><code>&lt;foo&gt;</code> vs <code>&lt;foo.h&gt;</code></a></li>
40 
   <li><a href="porting-howto.html">Porting HOWTO</a></li>
41 
   <li><a href="#5">Behavior specific to libstdc++-v3</a></li>
42 
   <li><a href="#6">Preprocessor macros controlling the library</a></li>
43 
</ul>
44 
 
45 
<hr />
46 
 
47 
<!-- ####################################################### -->
48 
 
49 
<h2><a name="2">The Standard C++ header files</a></h2>
50 
   <p>The Standard C++ Library specifies 50 header files that must be
51 
      available to all hosted implementations.  Actually, the word
52 
      &quot;files&quot; is a misnomer, since the contents of the headers
53 
      don't necessarily have to be in any kind of external file.  The
54 
      only rule is that when you <code>#include</code> a certain header, the
55 
      contents of that header, as defined by the Standard, become
56 
      available to you, no matter how.
57 
   </p>
58 
   <p>The names of the headers can be easily seen in
59 
      <a href="headers_cc.txt"><code>testsuite/17_intro/headers.cc</code></a>,
60 
      which is a small testbed we use to make certain that the headers
61 
      all compile and run.
62 
   </p>
63 
 
64 
<hr />
65 
<h2><a name="3">The Standard C++ library and multithreading</a></h2>
66 
   <p>This section discusses issues surrounding the proper compilation
67 
      of multithreaded applications which use the Standard C++
68 
      library.  This information is GCC-specific since the C++
69 
      standard does not address matters of multithreaded applications.
70 
      Unless explicitly prefaced, all information in this section is
71 
      current as of the GCC 3.0 release and all later point releases.
72 
   </p>
73 
   <p>Earlier GCC releases had a somewhat different approach to
74 
      threading configuration and proper compilation.  Before GCC 3.0,
75 
      configuration of the threading model was dictated by compiler
76 
      command-line options and macros (both of which were somewhat
77 
      thread-implementation and port-specific).  There were no
78 
      guarantees related to being able to link code compiled with one
79 
      set of options and macro setting with another set.  For GCC 3.0,
80 
      configuration of the threading model used with libraries and
81 
      user-code is performed when GCC is configured and built using
82 
      the --enable-threads and --disable-threads options.  The ABI is
83 
      stable for symbol name-mangling and limited functional
84 
      compatibility exists between code compiled under different
85 
      threading models.
86 
   </p>
87 
   <p>All normal disclaimers aside, multithreaded C++ application are
88 
      only supported when libstdc++ and all user code was built with
89 
      compilers which report (via <code> gcc/g++ -v </code>) the same thread
90 
      model and that model is not <em>single</em>.  As long as your
91 
      final application is actually single-threaded, then it should be
92 
      safe to mix user code built with a thread model of
93 
      <em>single</em> with a libstdc++ and other C++ libraries built
94 
      with another thread model useful on the platform.  Other mixes
95 
      may or may not work but are not considered supported.  (Thus, if
96 
      you distribute a shared C++ library in binary form only, it may
97 
      be best to compile it with a GCC configured with
98 
      --enable-threads for maximal interchangeability and usefulness
99 
      with a user population that may have built GCC with either
100 
      --enable-threads or --disable-threads.)
101 
   </p>
102 
   <p>When you link a multithreaded application, you will probably
103 
      need to add a library or flag to g++.  This is a very
104 
      non-standardized area of GCC across ports.  Some ports support a
105 
      special flag (the spelling isn't even standardized yet) to add
106 
      all required macros to a compilation (if any such flags are
107 
      required then you must provide the flag for all compilations not
108 
      just linking) and link-library additions and/or replacements at
109 
      link time.  The documentation is weak.  Here is a quick summary
110 
      to display how ad hoc this is: On Solaris, both -pthreads and
111 
      -threads (with subtly different meanings) are honored.  On OSF,
112 
      -pthread and -threads (with subtly different meanings) are
113 
      honored.  On Linux/i386, -pthread is honored.  On FreeBSD,
114 
      -pthread is honored.  Some other ports use other switches.
115 
      AFAIK, none of this is properly documented anywhere other than
116 
      in ``gcc -dumpspecs'' (look at lib and cpp entries).
117 
   </p>
118 
   <p>See <a href="../faq/index.html#3">FAQ</a> (general overview), <a
119 
      href="../23_containers/howto.html#3">23</a> (containers), and <a
120 
      href="../27_io/howto.html#9">27</a> (I/O) for more information.
121 
   </p>
122 
   <p>The libstdc++-v3 library (unlike libstdc++-v2, all of it, not
123 
      just the STL) has been designed so that multithreaded
124 
      applications using it may be written.  The first problem is
125 
      finding a <em>fast</em> method of implementation portable to all
126 
      platforms.  Due to historical reasons, some of the library is
127 
      written against per-CPU-architecture spinlocks and other parts
128 
      against the gthr.h abstraction layer which is provided by gcc.
129 
      A minor problem that pops up every so often is different
130 
      interpretations of what &quot;thread-safe&quot; means for a
131 
      library (not a general program).  We currently use the <a
132 
      href="http://www.sgi.com/tech/stl/thread_safety.html">same
133 
      definition that SGI</a> uses for their STL subset.  However, the
134 
      exception for read-only containers only applies to the STL
135 
      components.
136 
   </p>
137 
   <p>Here is a small link farm to threads (no pun) in the mail archives
138 
      that discuss the threading problem.  Each link is to the first
139 
      relevant message in the thread; from there you can use
140 
      &quot;Thread Next&quot; to move down the thread.  This farm is in
141 
      latest-to-oldest order.
142 
   </p>
143 
      <ul>
144 
        <li>Our threading expert Loren gives a breakdown of
145 
        <a href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the
146 
        six situations involving threads</a> for the 3.0 release series.</li>
147 
        <li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
148 
        This message</a> inspired a recent updating of issues with threading
149 
        and the SGI STL library.  It also contains some example
150 
        POSIX-multithreaded STL code.</li>
151 
      </ul>
152 
   <p> (A large selection of links to older messages has been removed; many
153 
      of the messages from 1999 were lost in a disk crash, and the few
154 
      people with access to the backup tapes have been too swamped with work
155 
      to restore them.  Many of the points have been superseded anyhow.)
156 
   </p>
157 
   <p>This section will be updated as new and interesting issues come
158 
      to light.
159 
   </p>
160 
   <p>Return <a href="#top">to top of page</a> or
161 
      <a href="../faq/index.html">to the FAQ</a>.
162 
   </p>
163 
 
164 
<hr />
165 
<h2><a name="4"><code>&lt;foo&gt;</code> vs <code>&lt;foo.h&gt;</code></a></h2>
166 
   <p>The new-style headers are fully supported in libstdc++-v3.  The compiler
167 
      itself fully supports namespaces, including <code>std::</code>.
168 
   </p>
169 
   <p>For those of you new to ISO C++98, no, that isn't a typo, the headers
170 
      really have new names.  Marshall Cline's C++ FAQ Lite has a good
171 
      explanation in
172 
<a href="http://www.parashift.com/c++-faq-lite/coding-standards.html#faq-27.4">item [27.4]</a>.
173 
   </p>
174 
   <p>Return <a href="#top">to top of page</a> or
175 
      <a href="../faq/index.html">to the FAQ</a>.
176 
   </p>
177 
 
178 
<hr />
179 
<h2><a name="5">Behavior specific to libstdc++-v3</a></h2>
180 
   <p>The ISO standard defines the following phrase:
181 
   </p>
182 
     <blockquote><dl>
183 
     <dt><code>[1.3.5] implementation-defined behavior</code></dt>
184 
     <dd>behavior, for a well-formed program construct and correct data, that
185 
         depends on the implementation <strong>and that each implementation
186 
         shall document</strong>.
187 
     </dd>
188 
     </dl></blockquote>
189 
   <p>We do so here, for the C++ library only.  Behavior of the compiler,
190 
      linker, runtime loader, and other elements of &quot;the
191 
      implementation&quot; are documented elsewhere.  Everything listed in
192 
      Annex B, Implemenation Qualities, are also part of the compiler, not
193 
      the library.
194 
   </p>
195 
   <p>For each entry, we give the section number of the standard, when
196 
      applicable.  This list is probably incomplet and inkorrekt.
197 
   </p>
198 
   <p><strong>[1.9]/11 #3</strong> If <code>isatty(3)</code> is true, then
199 
      interactive stream support is implied.
200 
   </p>
201 
   <p><strong>[17.4.4.5]</strong> Non-reentrant functions are probably best
202 
      discussed in the various sections on multithreading (see above).
203 
   </p>
204 
   <!-- [17.4.4.8]/3 says any function that doesn't have an exception-spec
205 
        can throw whatever we want; see also its footnote.  Let's list those
206 
        in the sections where the function itself occurs.
207 
   -->
208 
   <p><strong>[18.1]/4</strong> The type of <code>NULL</code> is described
209 
      <a href="../18_support/howto.html#1">here</a>.
210 
   </p>
211 
   <p><strong>[18.3]/8</strong> Even though it's listed in the library
212 
      sections, libstdc++-v3 has zero control over what the cleanup code hands
213 
      back to the runtime loader.  Talk to the compiler people.  :-)
214 
   </p>
215 
   <p><strong>[18.4.2.1]/5</strong> (bad_alloc),<br />
216 
      <strong>[18.5.2]/5</strong> (bad_cast),<br />
217 
      <strong>[18.5.3]/5</strong> (bad_typeid),<br />
218 
      <strong>[18.6.1]/8</strong> (exception),<br />
219 
      <strong>[18.6.2.1]/5</strong> (bad_exception):  The <code>what()</code>
220 
      member function of class <code>std::exception</code>, and these other
221 
      classes publicly derived from it, simply returns the name of the
222 
      class.  But they are the <em>mangled</em> names; you will need to call
223 
      <code>c++filt</code> and pass the names as command-line parameters to
224 
      demangle them, or call a
225 
      <a href="../18_support/howto.html#5">runtime demangler function</a>.
226 
      (The classes in <code>&lt;stdexcept&gt;</code> have constructors which
227 
      require an argument to use later for <code>what()</code> calls, so the
228 
      problem of <code>what()</code>'s value does not arise in most
229 
      user-defined exceptions.)
230 
   </p>
231 
   <p><strong>[18.5.1]/7</strong> The return value of
232 
      <code>std::type_info::name()</code> is the mangled type name (see the
233 
      previous entry for more).
234 
   </p>
235 
   <p><strong>[20.1.5]/5</strong> <em>&quot;Implementors are encouraged to
236 
      supply libraries that can accept allocators that encapsulate more
237 
      general memory models and that support non-equal instances.  In such
238 
      implementations, any requirements imposed on allocators by containers
239 
      beyond those requirements that appear in Table 32, and the semantics
240 
      of containers and algorithms when allocator instances compare
241 
      non-equal, are implementation-defined.&quot;</em>  As yet we don't
242 
      have any allocators which compare non-equal, so we can't describe how
243 
      they behave.
244 
   </p>
245 
   <p><strong>[21.1.3.1]/3,4</strong>,<br />
246 
      <strong>[21.1.3.2]/2</strong>,<br />
247 
      <strong>[23.*]'s foo::iterator</strong>,<br />
248 
      <strong>[27.*]'s foo::*_type</strong>,<br />
249 
      <strong>others...</strong>
250 
      Nope, these types are called implementation-defined because you
251 
      shouldn't be taking advantage of their underlying types.  Listing them
252 
      here would defeat the purpose.  :-)
253 
   </p>
254 
   <p><strong>[21.1.3.1]/5</strong> I don't really know about the mbstate_t
255 
      stuff... see the <a href="../22_locale/howto.html">chapter 22 notes</a>
256 
      for what does exist.
257 
   </p>
258 
   <p><strong>[22.*]</strong> Anything and everything we have on locale
259 
      implemenation will be described
260 
      <a href="../22_locale/howto.html">over here</a>.
261 
   </p>
262 
   <p><strong>[26.2.8]/9</strong> I have no idea what
263 
      <code>complex&lt;T&gt;</code>'s pow(0,0) returns.
264 
   </p>
265 
   <p><strong>[27.4.2.4]/2</strong> Calling
266 
      <code>std::ios_base::sync_with_stdio</code> after I/O has already been
267 
      performed on the standard stream objects will
268 
      flush the buffers, and <!-- this line might go away -->
269 
      destroy and recreate the underlying buffer instances.  Whether or not
270 
      the previously-written I/O is destroyed in this process depends mostly
271 
      on the --enable-libio choice:  for stdio, if the written data is
272 
      already in the stdio buffer, the data may be completely safe!
273 
   </p>
274 
   <p><strong>[27.6.1.1.2]</strong>,<br />
275 
      <strong>[27.6.2.3]</strong> The I/O sentry ctor and dtor can perform
276 
      additional work than the minimum required.  We are not currently taking
277 
      advantage of this yet.
278 
   </p>
279 
   <p><strong>[27.7.1.3]/16</strong>,<br />
280 
      <strong>[27.8.1.4]/10</strong>
281 
      The effects of <code>pubsetbuf/setbuf</code> are described
282 
      <a href="../27_io/howto.html#2">in this chapter</a>.
283 
   </p>
284 
   <p><strong>[27.8.1.4]/16</strong> Calling <code>fstream::sync</code> when
285 
      a get area exists will... whatever <code>fflush()</code> does, I think.
286 
   </p>
287 
   <p>Return <a href="#top">to top of page</a> or
288 
      <a href="../faq/index.html">to the FAQ</a>.
289 
   </p>
290 
 
291 
<hr />
292 
<h2><a name="6">Preprocessor macros controlling the library</a></h2>
293 
   <p>Some of the semantics of the libstdc++-v3 implementation are
294 
      controlled by preprocessor macros, both during build/installation and
295 
      during compilation of user code.  Many of these choices are made when
296 
      the library is built and installed (actually, during
297 
      <a href="../configopts.html">the configuration step</a>, with the
298 
      various --enable/--disable choices being translated to #define/#undef).
299 
   </p>
300 
   <p>All library macros begin with <code>_GLIBCPP_</code> in earlier
301 
      versions, and <code>_GLIBCXX_</code> in later versions.  The fact that
302 
      these symbols start with a leading underscore should give you a clue
303 
      that (by default) they aren't meant to be changed by the user.  :-)
304 
   </p>
305 
   <p>These macros are all gathered in the file <code>c++config.h</code>,
306 
      which is generated during installation.  <strong>You must assume that
307 
      these macros cannot be redefined by your own code</strong>, unless we
308 
      document otherwise here.  Some of the choices control code which has
309 
      already been compiled (i.e., libstdc++.a/.so).  If you explicitly
310 
      #define or #undef these macros, the <em>headers</em> may see different
311 
      code paths, but the <em>libraries</em> which you link against will not.
312 
      If you want to experiment with different values, you must change the
313 
      config headers before building/installing the library.
314 
   </p>
315 
   <p>Below are macros which, for 3.1 and later, you may change yourself,
316 
      in your own code with #define/#undef or with -D/-U compiler flags.
317 
      The default state of the symbol is listed.  &quot;Configurable&quot;
318 
      (or &quot;Not configurable&quot;) means that the symbol is initially
319 
      chosen (or not) based on --enable/--disable options at configure time.
320 
      For 3.1 through 3.3, the prefixes are <code>_GLIBCPP_</code>.
321 
   </p>
322 
    <dl>
323 
    <dt><code>_GLIBCXX_DEPRECATED</code></dt>
324 
    <dd>Undefined by default.  Not configurable.  Turning this on enables
325 
        older ARM-style iostreams code, and other anachronisms.  This may be
326 
        useful in updating old C++ programs which no longer meet the
327 
        requirements of the language.
328 
    </dd>
329 
    <!--
330 
     Can this actually be turned off and still produce a working lib?  Must
331 
     check.  -pme
332 
     No, it can't.  Hmmm.  -pme
333 
    <dt><code>_GLIBCPP_RESOLVE_LIB_DEFECTS</code></dt>
334 
    <dd>Defined by default.  Not configurable.  The library follows
335 
        corrections and updates from the ISO committee, see
336 
        <a href="../faq/index.html#5_2">here</a> and
337 
        <a href="../ext/howto.html#5">here</a> for more on this feature.
338 
        If you have code which depends on the first version of the standard,
339 
        you might try undefining this macro.
340 
    </dd>
341 
    -->
342 
    <dt><code>_GLIBCXX_CONCEPT_CHECKS</code></dt>
343 
    <dd>Undefined by default.  Configurable.  When defined, performs
344 
        compile-time checking on certain template instantiations to detect
345 
        violations of the requirements of the standard.  This is described
346 
        in more detail <a href="../19_diagnostics/howto.html#3">here</a>.
347 
    </dd>
348 
    <dt><code>_GLIBCXX_DEBUG</code></dt>
349 
    <dd>Undefined by default. Configurable. When defined, compiles
350 
    user code using the <a href="../debug.html#safe">libstdc++ debug
351 
    mode</a>.
352 
    </dd>
353 
    <dt><code>_GLIBCXX_DEBUG_PEDANTIC</code></dt>
354 
    <dd>Undefined by default. Configurable. When defined while
355 
    compiling with the <a href="../debug.html#safe">libstdc++ debug
356 
    mode</a>, makes the debug mode extremely picky by making the use
357 
    of libstdc++ extensions and libstdc++-specific behavior into
358 
    errors.
359 
    </dd>
360 
    <!--
361 
    <dt><code></code></dt>
362 
    <dd>
363 
    </dd>
364 
    -->
365 
    </dl>
366 
   <p>Return <a href="#top">to top of page</a> or
367 
      <a href="../faq/index.html">to the FAQ</a>.
368 
   </p>
369 
 
370 
 
371 
 
372 
<!-- ####################################################### -->
373 
 
374 
<hr />
375 
<p class="fineprint"><em>
376 
See <a href="license.html">license.html</a> for copying conditions.
377 
Comments and suggestions are welcome, and may be sent to
378 
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
379 
</em></p>
380 
 
381 
 
382 
</body>
383 
</html>
384 
 
385 
 

powered by: WebSVN 2.1.0

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