omp_threads(3)

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++:
          #include <omp.h>
          void omp_set_num_threads (integer-expression)

          #include <omp.h>
          int omp_get_num_threads()

          #include <omp.h>
          int omp_get_max_threads()

          #include <omp.h>
          int omp_get_thread_num()

          #include <omp.h>
          int omp_get_num_procs()

          #include <omp.h>
          void omp_set_dynamic(integer-expression)

          #include <omp.h>
          int omp_get_dynamic()

          #include <omp.h>
          int omp_in_parallel()

     Fortran:
          CALL OMP_SET_NUM_THREADS (integer-expression)

          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()

STANDARDS
     OpenMP Fortran API
     OpenMP C/C++ 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
     For the OpenMP directives to be honored by the compiler, you must
     specify -mp on your compiler command line explicitly.  In addition,
     -MP:open_mp=ON, which is the default setting, must be in effect.

     Example 1.

     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 ALSO
     omp_lock(3) for information on how to manipulate locks

     omp_nested(3) to manipulate or report status of nested parallelism