libgomp.texi

理解和实践操作系统的一本好书

\input texinfo @c -*-texinfo-*-

@c %**start of header
@setfilename libgomp.info
@settitle GNU libgomp
@c %**end of header


@copying
Copyright @copyright{} 2006 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'' and ``Funding
Free Software'', the Front-Cover
texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
``GNU Free Documentation License''.

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development.
@end copying

@ifinfo
@dircategory GNU Libraries
@direntry
* libgomp: (libgomp).                    GNU OpenMP runtime library
@end direntry

This manual documents the GNU implementation of the OpenMP API for 
multi-platform shared-memory parallel programming in C/C++ and Fortran.

Published by the Free Software Foundation
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301 USA

@insertcopying
@end ifinfo


@setchapternewpage odd

@titlepage
@title The GNU OpenMP Implementation
@page
@vskip 0pt plus 1filll
@comment For the @value{version-GCC} Version*
@sp 1
Published by the Free Software Foundation @*
51 Franklin Street, Fifth Floor@*
Boston, MA 02110-1301, USA@*
@sp 1
@insertcopying
@end titlepage

@summarycontents
@contents
@page


@node Top
@top Introduction
@cindex Introduction

This manual documents the usage of libgomp, the GNU implementation of the 
@uref{http://www.openmp.org, OpenMP} Application Programming Interface (API)
for multi-platform shared-memory parallel programming in C/C++ and Fortran.



@comment
@comment  When you add a new menu item, please keep the right hand
@comment  aligned to the same column.  Do not use tabs.  This provides
@comment  better formatting.
@comment
@menu
* Enabling OpenMP::            How to enable OpenMP for your applications.
* Runtime Library Routines::   The OpenMP runtime application programming 
                               interface.
* Environment Variables::      Influencing runtime behavior with environment 
                               variables.
* The libgomp ABI::            Notes on the external ABI presented by libgomp.
* Reporting Bugs::             How to report bugs in GNU OpenMP.
* Copying::                    GNU general public license says
                               how you can copy and share libgomp.
* GNU Free Documentation License::
                               How you can copy and share this manual.
* Funding::                    How to help assure continued work for free 
                               software.
* Index::                      Index of this documentation.
@end menu


@c ---------------------------------------------------------------------
@c Enabling OpenMP
@c ---------------------------------------------------------------------

@node Enabling OpenMP
@chapter Enabling OpenMP

To activate the OpenMP extensions for C/C++ and Fortran, the compile-time 
flag @command{-fopenmp} must be specified. This enables the OpenMP directive
@code{#pragma omp} in C/C++ and @code{!$omp} directives in free form, 
@code{c$omp}, @code{*$omp} and @code{!$omp} directives in fixed form, 
@code{!$} conditional compilation sentinels in free form and @code{c$},
@code{*$} and @code{!$} sentinels in fixed form, for Fortran. The flag also
arranges for automatic linking of the OpenMP runtime library 
(@ref{Runtime Library Routines}).

A complete description of all OpenMP directives accepted may be found in 
the @uref{http://www.openmp.org, OpenMP Application Program Interface} manual,
version 2.5.


@c ---------------------------------------------------------------------
@c Runtime Library Routines
@c ---------------------------------------------------------------------

@node Runtime Library Routines
@chapter Runtime Library Routines

The runtime routines described here are defined by section 3 of the OpenMP 
specifications in version 2.5.

Control threads, processors and the parallel environment.

@menu
* omp_get_dynamic::          Dynamic teams setting
* omp_get_max_threads::      Maximum number of threads
* omp_get_nested::           Nested parallel regions
* omp_get_num_procs::        Number of processors online
* omp_get_num_threads::      Size of the active team
* omp_get_thread_num::       Current thread ID
* omp_in_parallel::          Whether a parallel region is active
* omp_set_dynamic::          Enable/disable dynamic teams
* omp_set_nested::           Enable/disable nested parallel regions
* omp_set_num_threads::      Set upper team size limit
@end menu

Initialize, set, test, unset and destroy simple and nested locks.

@menu
* omp_init_lock::            Initialize simple lock
* omp_set_lock::             Wait for and set simple lock
* omp_test_lock::            Test and set simple lock if available
* omp_unset_lock::           Unset simple lock
* omp_destroy_lock::         Destroy simple lock
* omp_init_nest_lock::       Initialize nested lock
* omp_set_nest_lock::        Wait for and set simple lock
* omp_test_nest_lock::       Test and set nested lock if available
* omp_unset_nest_lock::      Unset nested lock
* omp_destroy_nest_lock::    Destroy nested lock
@end menu

Portable, thread-based, wall clock timer.

@menu
* omp_get_wtick::            Get timer precision.
* omp_get_wtime::            Elapsed wall clock time.
@end menu

@node omp_get_dynamic
@section @code{omp_get_dynamic} -- Dynamic teams setting
@table @asis
@item @emph{Description}:
This function returns @code{true} if enabled, @code{false} otherwise. 
Here, @code{true} and @code{false} represent their language-specific 
counterparts.

The dynamic team setting may be initialized at startup by the 
@code{OMP_DYNAMIC} environment variable or at runtime using 
@code{omp_set_dynamic}. If undefined, dynamic adjustment is 
disabled by default.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{int omp_get_dynamic();}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{logical function omp_get_dynamic()}
@end multitable

@item @emph{See also}:
@ref{omp_set_dynamic}, @ref{OMP_DYNAMIC}

@item @emph{Reference}:
@uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.8.
@end table



@node omp_get_max_threads
@section @code{omp_get_max_threads} -- Maximum number of threads
@table @asis
@item @emph{Description}:
Return the maximum number of threads used for parallel regions that do
not use the clause @code{num_threads}.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{int omp_get_max_threads();}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{integer function omp_get_max_threads()}
@end multitable

@item @emph{See also}:
@ref{omp_set_num_threads}, @ref{omp_set_dynamic}

@item @emph{Reference}:
@uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.3.
@end table



@node omp_get_nested
@section @code{omp_get_nested} -- Nested parallel regions
@table @asis
@item @emph{Description}:
This function returns @code{true} if nested parallel regions are
enabled, @code{false} otherwise. Here, @code{true} and @code{false} 
represent their language-specific counterparts.

Nested parallel regions may be initialized at startup by the 
@code{OMP_NESTED} environment variable or at runtime using 
@code{omp_set_nested}. If undefined, nested parallel regions are
disabled by default.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{int omp_get_nested();}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{integer function omp_get_nested()}
@end multitable

@item @emph{See also}:
@ref{omp_set_nested}, @ref{OMP_NESTED}

@item @emph{Reference}:
@uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.10.
@end table



@node omp_get_num_procs
@section @code{omp_get_num_procs} -- Number of processors online
@table @asis
@item @emph{Description}:
Returns the number of processors online.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{int omp_get_num_procs();}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{integer function omp_get_num_procs()}
@end multitable

@item @emph{Reference}:
@uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.5.
@end table



@node omp_get_num_threads
@section @code{omp_get_num_threads} -- Size of the active team
@table @asis
@item @emph{Description}:
The number of threads in the current team. In a sequential section of 
the program @code{omp_get_num_threads} returns 1.

The default team size may be initialized at startup by the 
@code{OMP_NUM_THREADS} environment variable. At runtime, the size 
of the current team may be set either by the @code{NUM_THREADS}
clause or by @code{omp_set_num_threads}. If none of the above were 
used to define a specific value and @code{OMP_DYNAMIC} is disabled,
one thread per CPU online is used.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{int omp_get_num_threads();}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{integer function omp_get_num_threads()}
@end multitable

@item @emph{See also}:
@ref{omp_get_max_threads}, @ref{omp_set_num_threads}, @ref{OMP_NUM_THREADS}

@item @emph{Reference}:
@uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.2.
@end table



@node omp_get_thread_num 
@section @code{omp_get_thread_num} -- Current thread ID
@table @asis
@item @emph{Description}:
Unique thread identification number. In a sequential parts of the program, 
@code{omp_get_thread_num} always returns 0. In parallel regions the return
value varies from 0 to @code{omp_get_max_threads}-1 inclusive. The return 
value of the master thread of a team is always 0.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{int omp_get_thread_num();}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{integer function omp_get_thread_num()}
@end multitable

@item @emph{See also}:
@ref{omp_get_max_threads}

@item @emph{Reference}:
@uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.4.
@end table



@node omp_in_parallel
@section @code{omp_in_parallel} -- Whether a parallel region is active
@table @asis
@item @emph{Description}:
This function returns @code{true} if currently running in parallel, 
@code{false} otherwise. Here, @code{true} and @code{false} represent 
their language-specific counterparts.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{int omp_in_parallel();}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{logical function omp_in_parallel()}
@end multitable

@item @emph{Reference}:
@uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.6.
@end table


@node omp_set_dynamic
@section @code{omp_set_dynamic} -- Enable/disable dynamic teams
@table @asis
@item @emph{Description}:
Enable or disable the dynamic adjustment of the number of threads 
within a team. The function takes the language-specific equivalent
of @code{true} and @code{false}, where @code{true} enables dynamic 
adjustment of team sizes and @code{false} disables it.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{void omp_set_dynamic(int);}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{subroutine omp_set_dynamic(set)}
@item                   @tab @code{integer, intent(in) :: set}
@end multitable

@item @emph{See also}:
@ref{OMP_DYNAMIC}, @ref{omp_get_dynamic}

@item @emph{Reference}:
@uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.7.
@end table



@node omp_set_nested
@section @code{omp_set_nested} -- Enable/disable nested parallel regions
@table @asis
@item @emph{Description}:
Enable or disable nested parallel regions, i.e., whether team members
are allowed to create new teams. The function takes the language-specific 
equivalent of @code{true} and @code{false}, where @code{true} enables 
dynamic adjustment of team sizes and @code{false} disables it.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{void omp_set_dynamic(int);}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{subroutine omp_set_dynamic(set)}
@item                   @tab @code{integer, intent(in) :: set}
@end multitable

@item @emph{See also}:
@ref{OMP_NESTED}, @ref{omp_get_nested}

@item @emph{Reference}:
@uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.9.
@end table



@node omp_set_num_threads
@section @code{omp_set_num_threads} -- Set upper team size limit
@table @asis
@item @emph{Description}:
Specifies the number of threads used by default in subsequent parallel 
sections, if those do not specify a @code{num_threads} clause. The 
argument of @code{omp_set_num_threads} shall be a positive integer. 

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{void omp_set_num_threads(int);}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{subroutine omp_set_num_threads(set)}
@item                   @tab @code{integer, intent(in) :: set}
@end multitable

@item @emph{See also}:
@ref{OMP_NUM_THREADS}, @ref{omp_get_num_threads}, @ref{omp_get_max_threads}

@item @emph{Reference}:
@uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.1.
@end table



@node omp_init_lock
@section @code{omp_init_lock} -- Initialize simple lock
@table @asis
@item @emph{Description}:
Initialize a simple lock. After initialization, the lock is in 
an unlocked state.

@item @emph{C/C++}: