OpenMP* Run-time Library Routines

OpenMP* provides run-time library routines to help you manage your program in parallel mode. Many of these run-time library routines have corresponding environment variables that can be set as defaults. The run-time library routines let you dynamically change these factors to assist in controlling your program. In all cases, a call to a run-time library routine overrides any corresponding environment variable. These routines are all external procedures.

CAUTION

Running OpenMP runtime library routines may initialize the OpenMP runtime environment, which might cause a situation where subsequent programmatic setting of OpenMP environment variables has no effect. To avoid this situation, you can use the Intel extension routine kmp_set_defaults() to set OpenMP environment variables.

The compiler supports all the OpenMP* run-time library routines. Refer to the OpenMP* API specification for detailed information about using these routines.

Include the appropriate declarations of the routines in the program unit containing the routine by adding a statement similar to the following:

Example
`use omp_lib`

The compiler provides module files in the ../include (Linux* and OS X*) or ..\include (Windows*) directory of your compiler installation.

Note

Some of the routines interfaces have offload equivalents. The offload equivalent takes two additional arguments to specify the target type and target number. For more information, see Calling Functions on the CPU to Modify the Coprocessor's Execution Environment.

The following table lists the keys that specify the data types of the dummy arguments for each of the listed routines:

Key	OMP_LIB Kind	BIND(C) Kind	KIND=
INTEGER ( `int` )	OMP_INTEGER_KIND	C_INT	4
LOGICAL ( `log` )	OMP_LOGICAL_KIND		4
REAL ( `dp` )	DOUBLE PRECISION	C_DOUBLE	8
INTEGER(OMP_LOCK_KIND)		C_INTPTR_T	intptr_t <<1>>
INTEGER(OMP_NEST_LOCK_KIND)		C_INTPTR_T	intptr_t <<1>>
INTEGER (OMP_SCHED_KIND)	OMP_INTEGER_KIND	C_INT	4
INTEGER(OMP_PROC_BIND_KIND)	OMP_INTEGER_KIND	C_INT	4
INTEGER(OMP_LOCK_HINT_KIND)		C_INTPTR_T	intptr_t <<1>>

intptr_t is an integer that is large enough to hold a pointer (address). With the Intel® Fortran Compiler, this is INTEGER(4) when building a 32-bit application and INTEGER(8) when building a 64-bit application. It is the value returned by the Intel Fortran intrinsic INT_PTR_KIND().

Execution Environment Routines

Use these routines to monitor and influence threads and the parallel environment.

Routine	Description
`SUBROUTINE OMP_SET_NUM_THREADS(num_threads)` `INTEGER(int) num_threads`	Sets the number of threads to use for subsequent parallel regions created by the calling thread.
`SUBROUTINE OMP_SET_DYNAMIC(dynamic_threads)` `LOGICAL dynamic_threads`	Enables or disables dynamic adjustment of the number of threads used to execute a parallel region. If `dynamic_threads` is .TRUE., dynamic threads are enabled. If `dynamic_threads` is .FALSE., dynamic threads are disabled. Dynamic threads are disabled by default.
`SUBROUTINE OMP_SET_NESTED(nested)` `LOGICAL(log) nested`	Enables or disables nested parallelism. If `nested` is .TRUE., nested parallelism is enabled. If `nested` is .FALSE., nested parallelism is disabled. Nested parallelism is disabled by default.
`INTEGER(int) FUNCTION OMP_GET_NUM_THREADS()`	Returns the number of threads that are being used in the current parallel region. This function does not necessarily return the value inherited by the calling thread from the OMP_SET_NUM_THREADS() function.
`INTEGER(int) FUNCTION OMP_GET_MAX_THREADS()`	Returns the number of threads available to subsequent parallel regions created by the calling thread.
`INTEGER(int) FUNCTION OMP_GET_THREAD_NUM()`	Returns the thread number of the calling thread, within the context of the current parallel region.
`INTEGER(int) FUNCTION OMP_GET_NUM_PROCS()`	Returns the number of processors available to the program.
`LOGICAL(log) FUNCTION OMP_IN_PARALLEL()`	Returns .TRUE. if called within the dynamic extent of a parallel region executing in parallel; otherwise returns .FALSE..
`LOGICAL(log) FUNCTION OMP_IN_FINAL()`	Returns .TRUE. if called within a final task region; otherwise returns .FALSE..
`LOGICAL(log) FUNCTION OMP_GET_DYNAMIC()`	Returns .TRUE. if dynamic thread adjustment is enabled, otherwise returns .FALSE..
`LOGICAL FUNCTION OMP_GET_NESTED()`	Returns .TRUE. if nested parallelism is enabled, otherwise returns .FALSE..
`INTEGER FUNCTION OMP_GET_THREAD_LIMIT()`	Returns the maximum number of simultaneously executing threads in an OpenMP* program.
`SUBROUTINE OMP_SET_MAX_ACTIVE_LEVELS(max_active_levels)` `INTEGER max_active_levels`	Limits the number of nested active parallel regions. The call is ignored if negative max_active_levels specified.
`INTEGER FUNCTION OMP_GET_MAX_ACTIVE_LEVELS()`	Returns the maximum number of nested active parallel regions.
`INTEGER FUNCTION OMP_GET_LEVEL()`	Returns the number of nested parallel regions (whether active or inactive) enclosing the task that contains the call, not including the implicit parallel region.
`INTEGER FUNCTION OMP_GET_ACTIVE_LEVEL()`	Returns the number of nested, active parallel regions enclosing the task that contains the call.
`INTEGER FUNCTION OMP_GET_ANCESTOR_THREAD_NUM(level)` `INTEGER level`	Returns the thread number of the ancestor at a given nest level of the current thread.
`INTEGER FUNCTION OMP_GET_TEAM_SIZE(level)` `INTEGER level`	Returns the size of the thread team to which the ancestor or the current thread belongs for the specified nested level of the current thread..
`SUBROUTINE OMP_SET_SCHEDULE(kind,chunk_size)` `INTEGER(KIND=omp_sched_kind) kind` `INTEGER(int) chunk_size`	Determines the schedule of a worksharing loop that is applied when '`runtime`' is used as the schedule kind.
`SUBROUTINE OMP_GET_SCHEDULE(kind,chunk_size)` `INTEGER(KIND=omp_sched_chunk_size) kind` `INTEGER(int) chunk_size`	Returns the schedule of a worksharing loop that is applied when the '`runtime`' schedule is used.
`INTEGER(KIND=OMP_PROC_BIND_KIND) OMP_GET_PROC_BIND()`	Returns the currently active thread affinity policy, which is set by environment variable OMP_PROC_BIND. This policy is used for subsequent nested parallel regions.
`INTEGER(int) FUNCTION OMP_GET_NUM_PLACES()`	Returns the number of places available to the execution environment in the place list of the initial task, usually threads, cores, or sockets.
`INTEGER(int) FUNCTION OMP_GET_PLACE_NUM_PROCS(place_num)` `INTEGER(int) place_num`	Returns the number of processors associated with the place numbered `place_num`. The routine returns zero when `place_num` is negative or is greater than or equal to OMP_GET_NUM_PLACES().
`SUBROUTINE OMP_GET_PLACE_PROC_IDS(place_num,ids) INTEGER(int) place_num INTEGER(int) ids(*)`	Returns the numerical identifiers of each processor associated with the place numbered place_num. The numerical identifiers are non-negative and their meaning is implementation defined. The numerical identifiers are returned in the array ids and their order in the array is implementation defined. ids must have at least OMP_GET_PLACE_NUM_PROCS(place_num) elements. The routine has no effect when `place_num` is greater than or equal to OMP_GET_NUM_PLACES().
`INTEGER(int) FUNCTION OMP_GET_PLACE_NUM()`	Returns the place number of the place to which the encountering thread is bound. The returned value is between 0 and OMP_GET_NUM_PLACES() - 1, inclusive. When the encountering thread is not bound to a place, the routine returns -1.
`INTEGER(int) FUNCTION OMP_GET_DEFAULT_DEVICE()`	Returns the default device number.
`SUBROUTINE OMP_SET_DEFAULT_DEVICE(device_number)` `INTEGER(int) device_number`	Sets the default device number.
`INTEGER(int) FUNCTION OMP_GET_NUM_DEVICES()`	Gets the number of target devices.
`INTEGER(int) FUNCTION OMP_GET_NUM_TEAMS()`	Gets the number of teams in the current teams region.
`INTEGER(int) FUNCTION OMP_GET_TEAM_NUM()`	Gets the team number of the calling thread.
`LOGICAL(log) FUNCTION OMP_GET_CANCELLATION()`	Returns .TRUE. if cancellation is enabled; otherwise, .FALSE.. This routine can be affected by the setting for environment variable OMP_CANCELLATION.
`LOGICAL(log) FUNCTION OMP_IS_INITIAL_DEVICE()`	Returns .TRUE. if the current task is running on the host device; otherwise, .FALSE..
`INTEGER(int) FUNCTION OMP_GET_INITIAL_DEVICE()`	Returns the device number of the host device. The value of the device number is implementation defined. If it is between 0 and OMP_GET_NUM_DEVICES()-1, then it is valid in all device constructs and routines; if it is outside that range, then it is only valid in the device memory routines and not in the DEVICE clause.
`INTEGER(int) FUNCTION OMP_GET_MAX_TASK_PRIORITY()`	Returns the maximum value that can be specified in the PRIORITY clause.

Lock Routines

Use these routines to affect OpenMP* locks.

Function	Description
`SUBROUTINE OMP_INIT_LOCK(svar)` `INTEGER (KIND=OMP_LOCK_KIND)svar`	Initializes the lock associated with the simple lock variable svar for use in subsequent calls.
`SUBROUTINE OMP_INIT_LOCK_WITH_HINT(svar, hint)` `INTEGER (KIND=OMP_LOCK_KIND)svar` `INTEGER (KIND=OMP_LOCK_HINT_KIND)hint`	Initializes the lock associated with svar to the unlocked state, optionally choosing a specific lock implementation based on `hint`.
`SUBROUTINE OMP_DESTROY_LOCK(svar)` `INTEGER(KIND=OMP_LOCK_KIND)svar`	Causes the lock specified by svar to become undefined or uninitialized. The lock must be initialized and not locked.
`SUBROUTINE OMP_SET_LOCK(svar)` `INTEGER(KIND=OMP_LOCK_KIND)svar`	Forces the executing thread to wait until the lock associated with svar is available. The thread is granted ownership of the lock when it becomes available. The lock must be initialized.
`SUBROUTINE OMP_UNSET_LOCK(svar)` `INTEGER(KIND=OMP_LOCK_KIND)svar`	Releases the executing thread from ownership of the lock associated with svar. The behavior is undefined if the executing thread does not own the lock associated with svar.
`LOGICAL(log) OMP_TEST_LOCK(svar)` `INTEGER(KIND=OMP_LOCK_KIND)svar`	Attempts to set the lock associated with svar. If successful, returns .TRUE., otherwise returns .FALSE.. The lock must be initialized.
`SUBROUTINE OMP_INIT_NEST_LOCK(nvar)` `INTEGER(KIND=OMP_NEST_LOCK_KIND)nvar`	Initializes the nested lock associated with the nested lock variable nvar for use in the subsequent calls.
`SUBROUTINE OMP_INIT_NEST_LOCK_WITH_HINT(nvar, hint)` `INTEGER (KIND=OMP_NEST_LOCK_KIND)nvar` `INTEGER (KIND=OMP_LOCK_HINT_KIND)hint`	Initializes the nested lock associated with nvar to the unlocked state, optionally choosing a specific lock implementation based on `hint`. The nesting count for nvar is set to zero.
`SUBROUTINE OMP_DESTROY_NEST_LOCK(nvar)` `INTEGER(KIND=OMP_NEST_LOCK_KIND)nvar`	Causes the nested lock associated with nvar to become undefined or uninitialized. The lock must be initialized and not locked.
`SUBROUTINE OMP_SET_NEST_LOCK(nvar)` `INTEGER(KIND=OMP_NEST_LOCK_KIND)nvar`	Forces the executing thread to wait until the nested lock associated with nvar is available. If the thread already owns the lock, then the lock nesting count is incremented.The lock must be initialized.
`SUBROUTINE OMP_UNSET_NEST_LOCK(nvar)` `INTEGER(KIND=OMP_NEST_LOCK_KIND)nvar`	Releases the executing thread from ownership of the nested lock associated with nvar if the nesting count is zero; otherwise, the nesting count is decremented. Behavior is undefined if the executing thread does not own the nested lock associated with nvar.
`INTEGER(int) OMP_TEST_NEST_LOCK(nvar)` `INTEGER(KIND=OMP_NEST_LOCK_KIND)nvar`	Attempts to set the nested lock specified by nvar. If successful, returns the nesting count, otherwise returns zero.

Timing Routines

Function	Description
`REAL (dp) FUNCTION OMP_GET_WTIME()`	Returns a double precision value equal to the elapsed wall clock time (in seconds) relative to an arbitrary reference time. The reference time does not change during program execution.
`REAL (dp) FUNCTION OMP_GET_WTICK()`	Returns a double precision value equal to the number of seconds between successive clock ticks.

The following parameter constants are defined in OMP_LIB.MOD and can be set or returned in the KIND dummy argument in OMP_SET_SCHEDULE and OMP_GET_SCHEDULE:

integer(omp_sched_kind), parameter :: omp_sched_static  = 1
integer(omp_sched_kind), parameter :: omp_sched_dynamic = 2
integer(omp_sched_kind), parameter :: omp_sched_guided  = 3
integer(omp_sched_kind), parameter :: omp_sched_auto    = 4

The following parameter constants are defined in OMP_LIB.MOD and represent values returned by OMP_GET_PROC_BIND:

integer (omp_proc_bind_kind), parameter :: omp_proc_bind_false  = 0
integer (omp_proc_bind_kind), parameter :: omp_proc_bind_true   = 1
integer (omp_proc_bind_kind), parameter :: omp_proc_bind_master = 2
integer (omp_proc_bind_kind), parameter :: omp_proc_bind_close  = 3
integer (omp_proc_bind_kind), parameter :: omp_proc_bind_spread = 4

The following parameter constants are defined in OMP_LIB.MOD and can be set in the HINT dummy argument in OMP_INIT_LOCK_WITH_HINT and OMP_INIT_NEST_LOCK_WITH_HINT:

integer (omp_lock_hint_kind), parameter :: omp_lock_hint_none           = 0
integer (omp_lock_hint_kind), parameter :: omp_lock_hint_uncontended    = 1
integer (omp_lock_hint_kind), parameter :: omp_lock_hint_contended      = 2
integer (omp_lock_hint_kind), parameter :: omp_lock_hint_nonspeculative = 4
integer (omp_lock_hint_kind), parameter :: omp_lock_hint_speculative    = 8

The hints can be combined by using the + operator in Fortran. The effect of the combined hint is implementation defined. Combining omp_lock_hint_none with any other hint is equivalent to specifying the other hint. The following restrictions apply to combined hints: