OMP_THREADS(3) Last changed: 2-24-98
NAME
omp_set_num_threads, omp_get_num_threads, omp_get_max_threads,
omp_get_thread_num, omp_get_num_procs, omp_set_dynamic,
omp_get)dynamic, omp_in_parallel, OMP_SET_NUM_THREADS,
OMP_GET_NUM_THREADS, OMP_GET_MAX_THREADS, OMP_GET_THREAD_NUM,
OMP_GET_NUM_PROCS, OMP_SET_DYNAMIC, OMP_GET_DYNAMIC, OMP_IN_PARALLEL -
Runtime library procedures used to set, call or return numbers of
threads
SYNOPSIS
C/C++: (Deferred implementation)
#include <omp_set_num_threads>
void omp_set_num_threads (integer-expression)
#include <omp_get_num_threads>
int omp_get_num_threads()
#include <omp_get_max_threads>
int omp_get_max_threads()
#include <omp_get_thread_num>
int omp_get_thread_num()
#include <omp_get_num_procs>
int omp_get_num_procs()
#integer <omp_set_dynamic>
void omp_set_dynamic(integer-expression)
#integer <omp_get_dynamic>
int omp_get_dynamic()
#integer <omp_in_parallel>
void omp_in_parallel()
Fortran:
CALL OMP_SET_NUM_THREADS (integer-epxression)
INTEGER OMP_GET_NUM_THREADS()
INTEGER OMP_GET_MAX_THREADS()
INTEGER OMP_GET_THREAD_NUM()
INTEGER OMP_GET_NUM_PROCS()
CALL OMP_SET_DYNAMIC(logical-expression)
LOGICAL OMP_GET_DYNAMIC()
LOGICAL OMP_IN_PARALLEL()IMPLEMENTATION
IRIX systems
STANDARDS
OpenMP Fortran API
DESCRIPTION
The following descriptions contain information for Fortran and C/C++.
omp_set_num_threads, OMP_SET_NUM_THREADS
This procedure sets the number of threads to use in a team.
The integer-expression is evaluated, and its value is used as the
number of threads to use beginning with the next non-nested parallel
region.
This call takes precedence over the OMP_NUM_THREADS environment
varable. When dynamic threads is enabled, this value is interpreted
to be the maximum number of threads to use.
omp_get_num_threads, OMP_GET_NUM_THREADS
This function returns the number of threads currently in the team
executing the parallel region from which it is called.
Mechanisms that control the number of threads include the runtime
system when dynamic adjustment of the number of threads is
enabled, the omp_set_num_threads() call (OMP_SET_NUM_THREADS
call), and the OMP_NUM_THREADS environment variable. The default
number of threads is implementation dependent in the case that
the number of threads has not been specified by the user.
This function binds to the closest enclosing parallel (PARALLEL)
directive. When called from a nested parallel region that is
serialized, this function returns 1.
omp_get_max_threads, OMP_GET_MAX_THREADS
This function returns the maximum value that calls to
omp_get_num_threads (OMP_GET_NUM_THREADS) may return. If
omp_set_num_threads (OMP_SET_NUM_THREADS) is called with a larger
value, subsequent calls o this function will return the larger
value. This function may be used to allocate maximal sized per-
thread data structures when omp_set_dynamic (OMP_SET_DYNAMIC) is
set to non-zero (TRUE). This function has global scope and
returns the maximum value whether executing from a serial region
or a parallel region.
omp_get_thread_num, OMP_GET_THREAD_NUM
This function returns the thread number within the team. The
master thread of the team is thread 0. The thread number is
between 0 and omp_get_num_threads()-1 (OMP_GET_NUM_THREADS()-1)
inclusive. This function binds to the closest enclosing parallel
(PARALLEL) directive. If called from a serial region, it returns
0. If called from within a nested parallel region that is
serialized, this function returns 0.
omp_get_num_procs, OMP_GET_NUM_PROCS
This function returns the number of processors that are available
to the program.
omp_set_dynamic, OMP_SET_DYNAMIC
This function enables or disables dynamic adjustment of the
number of threads available for execution of parallel regions.
If integer-expression (logical-expression) evaluates to non-zero
(TRUE), the number of threads that are used for executing
subsequent parallel regions may be adjusted automatically by the
runtime environment to best utilize system resources. As a
consequece, the number of threads specified by the user may
actually be interpreted as a maximum thread count. The number of
threads always remains fixed over the duration of each parallel
region and is reported by omp_get_num_threads()
(OMP_GET_NUM_THREADS). If integer-expression (logical-
expression) evaluates to zero (FALSE), dynamic adjustment is
disabled.
A call to omp_set_dynamic (OMP_SET_DYNAMIC) has precedence over
the OMP_DYNAMIC environment variable. The default for the
dynamic adjustment of threads is implementation dependent. As a
result, user codes that depend on a specific number of threads
for correct execution should explicitly disable dynamic threads.
Implementations are not required to provide the ability to
dynamically adjust the number of threads, but they are required
to provide the interface to support portability across all
platforms.
omp_get_dynamic, OMP_GET_DYNAMIC
This function returns non-zero (TRUE) if dynamic adjustment of
the number of threads is enabled; otherwise, it returns zero
(FALSE).
omp_in_parallel, OMP_IN_PARALLEL
This function returns non-zero (TRUE) if it is within the dynamic
extent of a parallel region that actually went parallel;
otherwise, it returns zero (FALSE). This function can be used to
determine whether it was called from within a parallel region.
It has global scope and will return TRUE from within a nested
parallel region.
ENVIRONMENT VARIABLES
OMP_SCHEDULE
This variable applies only to DO and PARALLEL DO directives that
have the schedule type RUNTIME. The schedule type and chunk size
for all such loops can be set at runtime by setting this
environment variable to any of the recognized schedule types and
to an optional chunk size. For DO and PARALLEL DO directives
that have a schedule type other than RUNTIME, this environment
variable is ignored. The default value for this environment
variable is implementation dependent. If the optional chunk size
is not set, a chunk size of 1 is assumed, except in the case of a
STATIC schedule, the chunk size is set to the loop iteration
space divided by the number of threads applied to the loop.
OMP_NUM_THREADS
This variable sets the number of threads to use during execution,
unless that number is explicitly changed by calling
omp_set_num_threads(). When dynamic adjustment of the number of
threads is enalbed, the value of this environment variable may be
interpreted as the maximum number of threads to use. The default
value is implementation dependent.
OMP_DYNAMIC
This variable enables or disables dynamic adjustment of the
number of threads available for execution of parallel regions.
If set to TRUE, the number of threads that are used for executing
parallel regions may be adjusted by the runtime environment to
best utilize system resources.
If set to FALSE, dynamic adjustment is disabled. The default
condition is implementation dependent.
OMP_NESTED
This variable enables or disables nested parallelism. If set to
TRUE, nested parallelism is enabled; if it is set to FALSE, it is
disabled. The default value is FALSE.
EXAMPLES
Example 1.
reviewers - the following paragraph contains some "implementation-
dependent" wording from the OpenMP standard. how should this
paragraph be modified for SGI/Cray's implementation of OpenMP?
Some programs rely on a fixed, prespecified number of threads to
execute correctly. Because the default setting for the dynamic
adjustment of the number of threads is implementation-dependent, such
programs can choose to turn off the dynamic threads capability and set
the number of threads explicitly. This ensures portability. The
following Fortran 90 code fragment specifies a fixed number of
threads:
CALL OMP_SET_DYNAMIC(.FALSE.)
CALL OMP_SET_NUM_THREADS(16)
!$OMP PARALLEL DEFAULT(PRIVATE)SHARED(X,NPOINTS)
IAM = OMP_GET_THREAD_NUM()
IPOINTS = NPOINTS/16
CALL DO_BY_16(X,IAM,IPOINTS)
!$OMP END PARALLEL
In the preceding code fragment, the code executes correctly only if it
is executed by 16 threads. Note that the number of threads executing
a parallel region remains constant during a parallel region,
regardless of the dynamic threads setting. The dynamic threads
mechanism determines the number of threads to use at the start of the
parallel region and keeps it constant for the duration of the region.
Example 2. Consider the following incorrect Fortran 90 code:
NP = OMP_GET_NUM_THREADS()
!$OMP PARALLEL DO SCHEDULE(STATIC)
DO I = 0, NP-1
CALL WORK(I)
ENDDO
!$OMP END PARALLEL DO
The OMP_GET_NUM_THREADS() call returns 1 in the serial section of the
code, so NP will always be equal to 1.
To determine the number of threads that will be deployed for the
parallel region, the call should be inside the parallel region. The
following code is a rewrite of the preceding code. It shows how to
rewrite the program without including a query for the number of
threads:
!$OMP PARALLEL PRIVATE(I)
I = OMP_GET_THREAD_NUM()
CALL WORK(I)
!$OMP END PARALLEL
SEE ALSOomp_lock(3) for information on how to manipulate locks
omp_nested(3) to manipulate or report status of nested parallelism
This man page is available only online.
