libgomp.texi

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

@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{void omp_init_lock(omp_lock_t *lock);}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{subroutine omp_init_lock(lock)}
@item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
@end multitable

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

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



@node omp_set_lock
@section @code{omp_set_lock} -- Wait for and set simple lock
@table @asis
@item @emph{Description}:
Before setting a simple lock, the lock variable must be initialized by 
@code{omp_init_lock}. The calling thread is blocked until the lock 
is available. If the lock is already held by the current thread, 
a deadlock occurs.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{void omp_set_lock(omp_lock_t *lock);}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{subroutine omp_set_lock(lock)}
@item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
@end multitable

@item @emph{See also}:
@ref{omp_init_lock}, @ref{omp_test_lock}, @ref{omp_unset_lock}

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



@node omp_test_lock
@section @code{omp_test_lock} -- Test and set simple lock if available
@table @asis
@item @emph{Description}:
Before setting a simple lock, the lock variable must be initialized by 
@code{omp_init_lock}. Contrary to @code{omp_set_lock}, @code{omp_test_lock} 
does not block if the lock is not available. This function returns 
@code{true} upon success,@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_test_lock(omp_lock_t *lock);}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{subroutine omp_test_lock(lock)}
@item                   @tab @code{logical(omp_logical_kind) :: omp_test_lock}
@item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
@end multitable

@item @emph{See also}:
@ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}

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



@node omp_unset_lock
@section @code{omp_unset_lock} -- Unset simple lock
@table @asis
@item @emph{Description}:
A simple lock about to be unset must have been locked by @code{omp_set_lock}
or @code{omp_test_lock} before. In addition, the lock must be held by the 
thread calling @code{omp_unset_lock}. Then, the lock becomes unlocked. If one 
ore more threads attempted to set the lock before, one of them is chosen to, 
again, set the lock for itself.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{void omp_unset_lock(omp_lock_t *lock);}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{subroutine omp_unset_lock(lock)}
@item                   @tab @code{integer(omp_lock_kind), intent(out) :: lock}
@end multitable

@item @emph{See also}:
@ref{omp_set_lock}, @ref{omp_test_lock}

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



@node omp_destroy_lock
@section @code{omp_destroy_lock} -- Destroy simple lock
@table @asis
@item @emph{Description}:
Destroy a simple lock. In order to be destroyed, a simple lock must be 
in the unlocked state. 

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

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{subroutine omp_destroy_lock(lock)}
@item                   @tab @code{integer(omp_lock_kind), intent(inout) :: lock}
@end multitable

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

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



@node omp_init_nest_lock
@section @code{omp_init_nest_lock} -- Initialize nested lock
@table @asis
@item @emph{Description}:
Initialize a nested lock. After initialization, the lock is in 
an unlocked state and the nesting count is set to zero.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{void omp_init_nest_lock(omp_nest_lock_t *lock);}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{subroutine omp_init_nest_lock(lock)}
@item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
@end multitable

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

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


@node omp_set_nest_lock
@section @code{omp_set_nest_lock} -- Wait for and set simple lock
@table @asis
@item @emph{Description}:
Before setting a nested lock, the lock variable must be initialized by 
@code{omp_init_nest_lock}. The calling thread is blocked until the lock 
is available. If the lock is already held by the current thread, the 
nesting count for the lock in incremented.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{void omp_set_nest_lock(omp_nest_lock_t *lock);}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{subroutine omp_set_nest_lock(lock)}
@item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
@end multitable

@item @emph{See also}:
@ref{omp_init_nest_lock}, @ref{omp_unset_nest_lock}

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



@node omp_test_nest_lock
@section @code{omp_test_nest_lock} -- Test and set nested lock if available
@table @asis
@item @emph{Description}:
Before setting a nested lock, the lock variable must be initialized by 
@code{omp_init_nest_lock}. Contrary to @code{omp_set_nest_lock}, 
@code{omp_test_nest_lock} does not block if the lock is not available. 
If the lock is already held by the current thread, the new nesting count 
is returned. Otherwise, the return value equals zero.

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

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{integer function omp_test_nest_lock(lock)}
@item                   @tab @code{integer(omp_integer_kind) :: omp_test_nest_lock}
@item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: lock}
@end multitable


@item @emph{See also}:
@ref{omp_init_lock}, @ref{omp_set_lock}, @ref{omp_set_lock}

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



@node omp_unset_nest_lock
@section @code{omp_unset_nest_lock} -- Unset nested lock
@table @asis
@item @emph{Description}:
A nested lock about to be unset must have been locked by @code{omp_set_nested_lock}
or @code{omp_test_nested_lock} before. In addition, the lock must be held by the 
thread calling @code{omp_unset_nested_lock}. If the nesting count drops to zero, the 
lock becomes unlocked. If one ore more threads attempted to set the lock before, 
one of them is chosen to, again, set the lock for itself.

@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{void omp_unset_nest_lock(omp_nest_lock_t *lock);}
@end multitable

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{subroutine omp_unset_nest_lock(lock)}
@item                   @tab @code{integer(omp_nest_lock_kind), intent(out) :: lock}
@end multitable

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

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



@node omp_destroy_nest_lock
@section @code{omp_destroy_nest_lock} -- Destroy nested lock
@table @asis
@item @emph{Description}:
Destroy a nested lock. In order to be destroyed, a nested lock must be 
in the unlocked state and its nesting count must equal zero.

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

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{subroutine omp_destroy_nest_lock(lock)}
@item                   @tab @code{integer(omp_nest_lock_kind), intent(inout) :: lock}
@end multitable

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

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



@node omp_get_wtick
@section @code{omp_get_wtick} -- Get timer precision
@table @asis
@item @emph{Description}:
Gets the timer precision, i.e., the number of seconds between two 
successive clock ticks.

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

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{double precision function omp_get_wtick()}
@end multitable

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

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



@node omp_get_wtime
@section @code{omp_get_wtime} -- Elapsed wall clock time
@table @asis
@item @emph{Description}:
Elapsed wall clock time in seconds. The time is measured per thread, no 
guarantee can bee made that two distinct threads measure the same time.
Time is measured from some "time in the past". On POSIX compliant systems 
the seconds since the Epoch (00:00:00 UTC, January 1, 1970) are returned.

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

@item @emph{Fortran}:
@multitable @columnfractions .20 .80
@item @emph{Interface}: @tab @code{double precision function omp_get_wtime()}
@end multitable

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

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



@c ---------------------------------------------------------------------
@c Environment Variables
@c ---------------------------------------------------------------------

@node Environment Variables
@chapter Environment Variables

The variables @env{OMP_DYNAMIC}, @env{OMP_NESTED}, @env{OMP_NUM_THREADS} and 
@env{OMP_SCHEDULE} are defined by section 4 of the OpenMP specifications in 
version 2.5, while @env{GOMP_CPU_AFFINITY} and @env{GOMP_STACKSIZE} are GNU 
extensions.

@menu
* OMP_DYNAMIC::        Dynamic adjustment of threads
* OMP_NESTED::         Nested parallel regions
* OMP_NUM_THREADS::    Specifies the number of threads to use
* OMP_SCHEDULE::       How threads are scheduled
* GOMP_CPU_AFFINITY::  Bind threads to specific CPUs
* GOMP_STACKSIZE::     Set default thread stack size
@end menu


@node OMP_DYNAMIC
@section @env{OMP_DYNAMIC} -- Dynamic adjustment of threads
@cindex Environment Variable
@cindex Implementation specific setting
@table @asis
@item @emph{Description}:
Enable or disable the dynamic adjustment of the number of threads 
within a team. The value of this environment variable shall be 
@code{TRUE} or @code{FALSE}. If undefined, dynamic adjustment is
disabled by default.

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

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



@node OMP_NESTED
@section @env{OMP_NESTED} -- Nested parallel regions
@cindex Environment Variable
@cindex Implementation specific setting
@table @asis
@item @emph{Description}:
Enable or disable nested parallel regions, i.e., whether team members
are allowed to create new teams. The value of this environment variable 
shall be @code{TRUE} or @code{FALSE}. If undefined, nested parallel 
regions are disabled by default.

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

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



@node OMP_NUM_THREADS
@section @env{OMP_NUM_THREADS} -- Specifies the number of threads to use
@cindex Environment Variable
@cindex Implementation specific setting
@table @asis
@item @emph{Description}:
Specifies the default number of threads to use in parallel regions. The 
value of this variable shall be positive integer. If undefined one thread 
per CPU online is used.

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

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



@node OMP_SCHEDULE
@section @env{OMP_SCHEDULE} -- How threads are scheduled
@cindex Environment Variable
@cindex Implementation specific setting
@table @asis
@item @emph{Description}:
Allows to specify @code{schedule type} and @code{chunk size}. 
The value of the variable shall have the form: @code{type[,chunk]} where
@code{type} is one of @code{static}, @code{dynamic} or @code{guided}. 
The optional @code{chunk size} shall be a positive integer. If undefined,
dynamic scheduling and a chunk size of 1 is used.

@item @emph{Reference}: 
@uref{http://www.openmp.org/, OpenMP specifications v2.5}, sections 2.5.1 and 4.1
@end table



@node GOMP_CPU_AFFINITY
@section @env{GOMP_CPU_AFFINITY} -- Bind threads to specific CPUs
@cindex Environment Variable
@table @asis
@item @emph{Description}:
Binds threads to specific CPUs. The variable should contain a space- or
comma-separated list of CPUs. This list may contain different kind of 
entries: either single CPU numbers in any order, a range of CPUs (M-N) 
or a range with some stride (M-N:S). CPU numbers are zero based. For example,
@code{GOMP_CPU_AFFINITY="0 3 1-2 4-15:2"} will bind the initial thread
to CPU 0, the second to CPU 3, the third to CPU 1, the fourth to 
CPU 2, the fifth to CPU 4, the sixth through tenth to CPUs 6, 8, 10, 12,
and 14 respectively and then start assigning back from the beginning of
the list. @code{GOMP_CPU_AFFINITY=0} binds all threads to CPU 0.

There is no GNU OpenMP library routine to determine whether a CPU affinity 
specification is in effect. As a workaround, language-specific library 
functions, e.g., @code{getenv} in C or @code{GET_ENVIRONMENT_VARIABLE} in 
Fortran, may be used to query the setting of the @code{GOMP_CPU_AFFINITY} 
environment variable. A defined CPU affinity on startup cannot be changed 
or disabled during the runtime of the application.

If this environment variable is omitted, the host system will handle the 
assignment of threads to CPUs. 
@end table