URL https://opencores.org/ocsvn/openrisc/openrisc/trunk
Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-stable/] [gcc-4.5.1/] [libstdc++-v3/] [doc/] [xml/] [manual/] [using.xml] - Blame information for rev 862

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



 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[ ]>
 

  
 
Using
 
 
  
    Command Options
    
      The set of features available in the GNU C++ library is shaped
      by
      several GCC
      Command Options. Options that impact libstdc++ are
      enumerated and detailed in the table below.
    
 
    
      By default, g++ is equivalent to  g++ -std=gnu++98. The standard library also defaults to this dialect.
    
 

 
  
 
  
    
    Headers
 
    
      Header Files
 
   
     The C++ standard specifies the entire set of header files that
     must be available to all hosted implementations.  Actually, the
     word "files" is a misnomer, since the contents of the
     headers don't necessarily have to be in any kind of external
     file.  The only rule is that when one #include's a
     header, the contents of that header become available, no matter
     how.
   
 
   
   That said, in practice files are used.
   
 
   
     There are two main types of include files: header files related
     to a specific version of the ISO C++ standard (called Standard
     Headers), and all others (TR1, C++ ABI, and Extensions).
   
 
   
     Two dialects of standard headers are supported, corresponding to
     the 1998 standard as updated for 2003, and the draft of the
     upcoming 200x standard.
   
 
   
     C++98/03 include files. These are available in the default compilation mode, i.e. -std=c++98 or -std=gnu++98.
   
 

 


 

C++0x include files. These are only available in C++0x compilation
mode, i.e. -std=c++0x or -std=gnu++0x.

 


 

 

 
 

  In addition, TR1 includes as:

 

 

 
 

 
 
Decimal floating-point arithmetic is available if the C++
compiler supports scalar decimal floating-point types defined via
__attribute__((mode(SD|DD|LD))).

 

 

  Also included are files for the C++ ABI interface:

 

 

  And a large variety of extensions.

 

 

 

 

 

 

 

 
    
 
    
      Mixing Headers
 
 A few simple rules.

 
First, mixing different dialects of the standard headers is not
possible. It's an all-or-nothing affair. Thus, code like

 

#include <array>
#include <functional>

 
Implies C++0x mode. To use the entities in <array>, the C++0x
compilation mode must be used, which implies the C++0x functionality
(and deprecations) in <functional> will be present.

 
Second, the other headers can be included with either dialect of
the standard headers, although features and types specific to C++0x
are still only enabled when in C++0x compilation mode. So, to use
rvalue references with __gnu_cxx::vstring, or to use the
debug-mode versions of std::unordered_map, one must use
the std=gnu++0x compiler flag. (Or std=c++0x, of course.)

 
A special case of the second rule is the mixing of TR1 and C++0x
facilities. It is possible (although not especially prudent) to
include both the TR1 version and the C++0x version of header in the
same translation unit:

 

#include <tr1/type_traits>
#include <type_traits>

 
 Several parts of C++0x diverge quite substantially from TR1 predecessors.

    
 
    
      The C Headers and <code>namespace std</code>
 

        The standard specifies that if one includes the C-style header
        (<math.h> in this case), the symbols will be available
        in the global namespace and perhaps in
        namespace std:: (but this is no longer a firm
        requirement.) On the other hand, including the C++-style
        header (<cmath>) guarantees that the entities will be
        found in namespace std and perhaps in the global namespace.
      
 

Usage of C++-style headers is recommended, as then
C-linkage names can be disambiguated by explicit qualification, such
as by std::abort. In addition, the C++-style headers can
use function overloading to provide a simpler interface to certain
families of C-functions. For instance in <cmath>, the
function std::sin has overloads for all the builtin
floating-point types. This means that std::sin can be
used uniformly, instead of a combination
of std::sinf, std::sin,
and std::sinl.

    
 
    
      Precompiled Headers
 
 
There are three base header files that are provided. They can be
used to precompile the standard headers and extensions into binary
files that may the be used to speed compiles that use these headers.

 
 


  stdc++.h
Includes all standard headers. Actual content varies depending on
language dialect.


 

  stdtr1c++.h
Includes all of <stdc++.h>, and adds all the TR1 headers.


 
extc++.h
Includes all of <stdtr1c++.h>, and adds all the Extension headers.


 
How to construct a .gch file from one of these base header files.
 
First, find the include directory for the compiler. One way to do
this is:
 

g++ -v hello.cc
 
#include <...> search starts here:
 /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0
...
End of search list.

 
 
Then, create a precompiled header file with the same flags that
will be used to compile other projects.
 

g++ -Winvalid-pch -x c++-header -g -O2 -o ./stdc++.h.gch /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/x86_64-unknown-linux-gnu/bits/stdc++.h

 
The resulting file will be quite large: the current size is around
thirty megabytes. 
 
How to use the resulting file.
 

g++ -I. -include stdc++.h  -H -g -O2 hello.cc

 
Verification that the PCH file is being used is easy:
 

g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
! ./stdc++.h.gch
. /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream
. /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string

 
The exclamation point to the left of the stdc++.h.gch listing means that the generated PCH file was used, and thus the 

 
 Detailed information about creating precompiled header files can be found in the GCC documentation.

 
    
  
 
 
  
    
    Macros
 
   
     All library macros begin with _GLIBCXX_.
   
 
   
     Furthermore, all pre-processor macros, switches, and
      configuration options are gathered in the
      file c++config.h, which
      is generated during the libstdc++ configuration and build
      process. This file is then included when needed by files part of
      the public libstdc++ API, like <ios>. Most of these macros
      should not be used by consumers of libstdc++, and are reserved
      for internal implementation use. These macros cannot
      be redefined.
   
 
   
     A select handful of macros control libstdc++ extensions and extra
      features, or provide versioning information for the API.  Only
      those macros listed below are offered for consideration by the
      general public.
   
 
   Below is the macro which users may check for library version
      information. 
 
    
    
      __GLIBCXX__
      
        The current version of
    libstdc++ in compressed ISO date format, form of an unsigned
    long. For details on the value of this particular macro for a
    particular release, please consult this 
    document.
    
    
    
    
 
   Below are the macros which users may change with #define/#undef or
      with -D/-U compiler flags.  The default state of the symbol is
      listed.
 
   Configurable (or Not configurable) means
      that the symbol is initially chosen (or not) based on
      --enable/--disable options at library build and configure time
      (documented here), with the
      various --enable/--disable choices being translated to
      #define/#undef).
   
 
    ABI means that changing from the default value may
  mean changing the ABI of compiled code. In other words, these
  choices control code which has already been compiled (i.e., in a
  binary such as libstdc++.a/.so).  If you explicitly #define or
  #undef these macros, the headers may see different code
  paths, but the libraries which you link against will not.
  Experimenting with different values with the expectation of
  consistent linkage requires changing the config headers before
  building/installing the library.
   
 
    
    _GLIBCXX_DEPRECATED
    
      
        Defined by default. Not configurable. ABI-changing. Turning this off
        removes older ARM-style iostreams code, and other anachronisms
        from the API.  This macro is dependent on the version of the
        standard being tracked, and as a result may give different results for
        -std=c++98 and -std=c++0x. This may
        be useful in updating old C++ code which no longer meet the
        requirements of the language, or for checking current code
        against new language standards.
    
    
 
    _GLIBCXX_FORCE_NEW
    
      
        Undefined by default. When defined, memory allocation and
        allocators controlled by libstdc++ call operator new/delete
        without caching and pooling. Configurable via
        --enable-libstdcxx-allocator. ABI-changing.
      
    
 
 
    _GLIBCXX_CONCEPT_CHECKS
    
      
        Undefined by default.  Configurable via
        --enable-concept-checks.  When defined, performs
        compile-time checking on certain template instantiations to
        detect violations of the requirements of the standard.  This
        is described in more detail 
        linkend="manual.ext.compile_checks">here.
      
    
 
    _GLIBCXX_DEBUG
    
      
        Undefined by default. When defined, compiles user code using
    the debug mode.
      
    
    _GLIBCXX_DEBUG_PEDANTIC
    
      
        Undefined by default. When defined while compiling with
    the debug mode, makes
    the debug mode extremely picky by making the use of libstdc++
    extensions and libstdc++-specific behavior into errors.
      
    
    _GLIBCXX_PARALLEL
    
      Undefined by default. When defined, compiles user code
    using the parallel
    mode.
      
    
 
    _GLIBCXX_PROFILE
    
      Undefined by default. When defined, compiles user code
    using the profile
    mode.
      
    
    
 
  
 
  
    
    Namespaces
 
    
      Available Namespaces
 
 
 
 There are three main namespaces.

 

  std
The ISO C++ standards specify that "all library entities are defined
within namespace std." This includes namespaces nested
within namespace std, such as namespace
std::tr1.


abi
Specified by the C++ ABI. This ABI specifies a number of type and
function APIs supplemental to those required by the ISO C++ Standard,
but necessary for interoperability.


 
__gnu_
Indicating one of several GNU extensions. Choices
include __gnu_cxx, __gnu_debug, __gnu_parallel,
and __gnu_pbds.


 
 A complete list of implementation namespaces (including namespace contents) is available in the generated source documentation.

 
 
    
 
    
      namespace std
 
 

      One standard requirement is that the library components are defined
      in namespace std::. Thus, in order to use these types or
      functions, one must do one of two things:

 

  put a kind of using-declaration in your source
(either using namespace std; or i.e. using
std::string;) This approach works well for individual source files, but
should not be used in a global context, like header files.
           use a fully
qualified name for each library symbol
(i.e. std::string, std::cout) Always can be
used, and usually enhanced, by strategic use of typedefs. (In the
cases where the qualified verbiage becomes unwieldy.)
          
        

 
    
 
    
      Using Namespace Composition
 

Best practice in programming suggests sequestering new data or
functionality in a sanely-named, unique namespace whenever
possible. This is considered an advantage over dumping everything in
the global namespace, as then name look-up can be explicitly enabled or
disabled as above, symbols are consistently mangled without repetitive
naming prefixes or macros, etc.

 
For instance, consider a project that defines most of its classes in namespace gtk. It is possible to
        adapt namespace gtk to namespace std by using a C++-feature called
        namespace composition. This is what happens if
        a using-declaration is put into a
        namespace-definition: the imported symbol(s) gets imported into the
        currently active namespace(s). For example:


namespace gtk
{
  using std::string;
  using std::tr1::array;
 
  class Window { ... };
}


        In this example, std::string gets imported into
        namespace gtk.  The result is that use of
        std::string inside namespace gtk can just use string, without the explicit qualification.
        As an added bonus,
        std::string does not get imported into
        the global namespace.  Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
        using-declarations can wrapped in macros that
        are set based on autoconf-tests to either "" or i.e. using
          std::string; (depending on whether the system has
        libstdc++ in std:: or not).  (ideas from
        Llewelly and Karl Nelson)

 
 
    
  
 
  
    
    Linking
 
    
      Almost Nothing
      
        Or as close as it gets: freestanding. This is a minimal
        configuration, with only partial support for the standard
        library. Assume only the following header files can be used:
      
 
      
        
          
            cstdarg
          
        
 
        
          
          cstddef
          
        
 
        
          
          cstdlib
          
        
 
        
          
          exception
          
        
 
        
          
          limits
          
        
 
        
          
          new
          
        
 
        
          
          exception
          
        
 
        
          
          typeinfo
          
        
      
 
      
        In addition, throw in
      
 
      
        
          
          cxxabi.h.
          
        
      
 
      
        In the
        C++0x dialect add
      
 
      
        
          
          initializer_list
          
        
        
          
          type_traits
          
        
      
 
       There exists a library that offers runtime support for
        just these headers, and it is called
        libsupc++.a. To use it, compile with gcc instead of g++, like so:
      
 
      
        gcc foo.cc -lsupc++
      
 
      
        No attempt is made to verify that only the minimal subset
        identified above is actually used at compile time. Violations
        are diagnosed as undefined symbols at link time.
      
    
 
    
      Finding Dynamic or Shared Libraries
 
    
      If the only library built is the static library
      (libstdc++.a), or if
      specifying static linking, this section is can be skipped.  But
      if building or using a shared library
      (libstdc++.so), then
      additional location information will need to be provided.
    
    
      But how?
    
    
A quick read of the relevant part of the GCC
      manual, Compiling
      C++ Programs, specifies linking against a C++
      library. More details from the
      GCC FAQ,
      which states GCC does not, by default, specify a
      location so that the dynamic linker can find dynamic libraries at
      runtime.
    
    
      Users will have to provide this information.
    
    
      Methods vary for different platforms and different styles, and
      are printed to the screen during installation. To summarize:
    
    
      
        
          At runtime set LD_LIBRARY_PATH in your
          environment correctly, so that the shared library for
          libstdc++ can be found and loaded.  Be certain that you
          understand all of the other implications and behavior
          of LD_LIBRARY_PATH first.
        
 
      
      
        
          Compile the path to find the library at runtime into the
          program.  This can be done by passing certain options to
          g++, which will in turn pass them on to
          the linker.  The exact format of the options is dependent on
          which linker you use:
        
        
          
            
              GNU ld (default on Linux):-Wl,--rpath,destdir/lib
            
          
          
            
              IRIX ld:
              -Wl,-rpath,destdir/lib
            
          
          
          
          Solaris ld:-Wl,-Rdestdir/lib
          
          
        
      
    
    
      Use the ldd utility on the linked executable
      to show
      which libstdc++.so
      library the system will get at runtime.
    
    
      A libstdc++.la file is
      also installed, for use with Libtool.  If you use Libtool to
      create your executables, these details are taken care of for
      you.
    
    
  
 
 
  
    
    Concurrency
 
   This section discusses issues surrounding the proper compilation
      of multithreaded applications which use the Standard C++
      library.  This information is GCC-specific since the C++
      standard does not address matters of multithreaded applications.
   
 
    
      Prerequisites
 
   All normal disclaimers aside, multithreaded C++ application are
      only supported when libstdc++ and all user code was built with
      compilers which report (via  gcc/g++ -v ) the same thread
      model and that model is not single.  As long as your
      final application is actually single-threaded, then it should be
      safe to mix user code built with a thread model of
      single with a libstdc++ and other C++ libraries built
      with another thread model useful on the platform.  Other mixes
      may or may not work but are not considered supported.  (Thus, if
      you distribute a shared C++ library in binary form only, it may
      be best to compile it with a GCC configured with
      --enable-threads for maximal interchangeability and usefulness
      with a user population that may have built GCC with either
      --enable-threads or --disable-threads.)
   
   When you link a multithreaded application, you will probably
      need to add a library or flag to g++.  This is a very
      non-standardized area of GCC across ports.  Some ports support a
      special flag (the spelling isn't even standardized yet) to add
      all required macros to a compilation (if any such flags are
      required then you must provide the flag for all compilations not
      just linking) and link-library additions and/or replacements at
      link time.  The documentation is weak.  Here is a quick summary
      to display how ad hoc this is: On Solaris, both -pthreads and
      -threads (with subtly different meanings) are honored.  On OSF,
      -pthread and -threads (with subtly different meanings) are
      honored.  On Linux/i386, -pthread is honored.  On FreeBSD,
      -pthread is honored.  Some other ports use other switches.
      AFAIK, none of this is properly documented anywhere other than
      in ``gcc -dumpspecs'' (look at lib and cpp entries).
   
 
    
 
    
      Thread Safety
 
 

We currently use the SGI STL definition of thread safety.

 
 
      The library strives to be thread-safe when all of the following
         conditions are met:
      
      
       
       The system's libc is itself thread-safe,
       
       
       
         
           The compiler in use reports a thread model other than
           'single'. This can be tested via output from gcc
           -v. Multi-thread capable versions of gcc output
           something like this:
         

%gcc -v
Using built-in specs.
...
Thread model: posix
gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)

 
Look for "Thread model" lines that aren't equal to "single."
       
       
       
         Requisite command-line flags are used for atomic operations
         and threading. Examples of this include -pthread
         and -march=native, although specifics vary
         depending on the host environment. See 
         url="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine
         Dependent Options.
       
       
       
         
           An implementation of atomicity.h functions
           exists for the architecture in question. See the internals documentation for more details.
       
       
 
      
      The user-code must guard against concurrent method calls which may
         access any particular library object's state.  Typically, the
         application programmer may infer what object locks must be held
         based on the objects referenced in a method call.  Without getting
         into great detail, here is an example which requires user-level
         locks:
      
      
     library_class_a shared_object_a;
 
     thread_main () {
       library_class_b *object_b = new library_class_b;
       shared_object_a.add_b (object_b);   // must hold lock for shared_object_a
       shared_object_a.mutate ();          // must hold lock for shared_object_a
     }
 
     // Multiple copies of thread_main() are started in independent threads.
      Under the assumption that object_a and object_b are never exposed to
         another thread, here is an example that should not require any
         user-level locks:
      
      
     thread_main () {
       library_class_a object_a;
       library_class_b *object_b = new library_class_b;
       object_a.add_b (object_b);
       object_a.mutate ();
     } 
      All library objects are safe to use in a multithreaded program as
         long as each thread carefully locks out access by any other
         thread while it uses any object visible to another thread, i.e.,
         treat library objects like any other shared resource.  In general,
         this requirement includes both read and write access to objects;
         unless otherwise documented as safe, do not assume that two threads
         may access a shared standard library object at the same time.
      
 
 
  
  
    Atomics
    
    
  
 
    
      IO
     This gets a bit tricky.  Please read carefully, and bear with me.
   
 
    
      Structure
   A wrapper
      type called __basic_file provides our abstraction layer
      for the std::filebuf classes.  Nearly all decisions dealing
      with actual input and output must be made in __basic_file.
   
   A generic locking mechanism is somewhat in place at the filebuf layer,
      but is not used in the current code.  Providing locking at any higher
      level is akin to providing locking within containers, and is not done
      for the same reasons (see the links above).
   
    
 
    
      Defaults
   The __basic_file type is simply a collection of small wrappers around
      the C stdio layer (again, see the link under Structure).  We do no
      locking ourselves, but simply pass through to calls to fopen,
      fwrite, and so forth.
   
   So, for 3.0, the question of "is multithreading safe for I/O"
      must be answered with, "is your platform's C library threadsafe
      for I/O?"  Some are by default, some are not; many offer multiple
      implementations of the C library with varying tradeoffs of threadsafety
      and efficiency.  You, the programmer, are always required to take care
      with multiple threads.
   
   (As an example, the POSIX standard requires that C stdio FILE*
       operations are atomic.  POSIX-conforming C libraries (e.g, on Solaris
       and GNU/Linux) have an internal mutex to serialize operations on
       FILE*s.  However, you still need to not do stupid things like calling
       fclose(fs) in one thread followed by an access of
       fs in another.)
   
   So, if your platform's C library is threadsafe, then your
      fstream I/O operations will be threadsafe at the lowest
      level.  For higher-level operations, such as manipulating the data
      contained in the stream formatting classes (e.g., setting up callbacks
      inside an std::ofstream), you need to guard such accesses
      like any other critical shared resource.
   
    
 
    
      Future
    A
      second choice may be available for I/O implementations:  libio.  This is
      disabled by default, and in fact will not currently work due to other
      issues.  It will be revisited, however.
   
   The libio code is a subset of the guts of the GNU libc (glibc) I/O
      implementation.  When libio is in use, the __basic_file
      type is basically derived from FILE.  (The real situation is more
      complex than that... it's derived from an internal type used to
      implement FILE.  See libio/libioP.h to see scary things done with
      vtbls.)  The result is that there is no "layer" of C stdio
      to go through; the filebuf makes calls directly into the same
      functions used to implement fread, fwrite,
      and so forth, using internal data structures.  (And when I say
      "makes calls directly," I mean the function is literally
      replaced by a jump into an internal function.  Fast but frightening.
      *grin*)
   
   Also, the libio internal locks are used.  This requires pulling in
      large chunks of glibc, such as a pthreads implementation, and is one
      of the issues preventing widespread use of libio as the libstdc++
      cstdio implementation.
   
   But we plan to make this work, at least as an option if not a future
      default.  Platforms running a copy of glibc with a recent-enough
      version will see calls from libstdc++ directly into the glibc already
      installed.  For other platforms, a copy of the libio subsection will
      be built and included in libstdc++.
   
    
 
    
      Alternatives
   Don't forget that other cstdio implementations are possible.  You could
      easily write one to perform your own forms of locking, to solve your
      "interesting" problems.
   
    
 
    
 
    
      Containers
 
   This section discusses issues surrounding the design of
      multithreaded applications which use Standard C++ containers.
      All information in this section is current as of the gcc 3.0
      release and all later point releases.  Although earlier gcc
      releases had a different approach to threading configuration and
      proper compilation, the basic code design rules presented here
      were similar.  For information on all other aspects of
      multithreading as it relates to libstdc++, including details on
      the proper compilation of threaded code (and compatibility between
      threaded and non-threaded code), see Chapter 17.
   
   Two excellent pages to read when working with the Standard C++
      containers and threads are
      SGI's
      http://www.sgi.com/tech/stl/thread_safety.html and
      SGI's
      http://www.sgi.com/tech/stl/Allocators.html.
   
   However, please ignore all discussions about the user-level
      configuration of the lock implementation inside the STL
      container-memory allocator on those pages.  For the sake of this
      discussion, libstdc++ configures the SGI STL implementation,
      not you.  This is quite different from how gcc pre-3.0 worked.
      In particular, past advice was for people using g++ to
      explicitly define _PTHREADS or other macros or port-specific
      compilation options on the command line to get a thread-safe
      STL.  This is no longer required for any port and should no
      longer be done unless you really know what you are doing and
      assume all responsibility.
   
   Since the container implementation of libstdc++ uses the SGI
      code, we use the same definition of thread safety as SGI when
      discussing design.  A key point that beginners may miss is the
      fourth major paragraph of the first page mentioned above
      (For most clients...), which points out that
      locking must nearly always be done outside the container, by
      client code (that'd be you, not us).  There is a notable
      exceptions to this rule.  Allocators called while a container or
      element is constructed uses an internal lock obtained and
      released solely within libstdc++ code (in fact, this is the
      reason STL requires any knowledge of the thread configuration).
   
   For implementing a container which does its own locking, it is
      trivial to provide a wrapper class which obtains the lock (as
      SGI suggests), performs the container operation, and then
      releases the lock.  This could be templatized to a certain
      extent, on the underlying container and/or a locking
      mechanism.  Trying to provide a catch-all general template
      solution would probably be more trouble than it's worth.
   
   The library implementation may be configured to use the
      high-speed caching memory allocator, which complicates thread
      safety issues. For all details about how to globally override
      this at application run-time
      see here. Also
      useful are details
      on allocator
      options and capabilities.
   
 
    

 


            parse="xml" href="using_exceptions.xml">

 


            parse="xml" href="debug.xml">

 

Browse

Tools

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-stable/] [gcc-4.5.1/] [libstdc++-v3/] [doc/] [xml/] [manual/] [using.xml] - Blame information for rev 862
