OpenMP* Runtime Library Routines

Developer Guide and Reference

Download PDF

ID 767251

Date 10/31/2024

Version

Public

OpenMP* Runtime Library Routines

OpenMP* provides runtime library routines to help you manage your program in parallel mode. Many of these runtime library routines have corresponding environment variables that can be set as defaults. The runtime library routines let you dynamically change these factors to assist in controlling your program. In all cases, a call to a runtime 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 runtime 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:


use omp_lib

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

The integer parameter openmp_version in omp_lib.mod (and omp_lib.h, an INCLUDE version of omp_lib.mod) has the decimal value yyyymm where yyyy and mm are the year and month of the version of the OpenMP API supported by the current version of the compiler and libraries. See the predefined preprocessor symbol _OPENMP for more information.

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

Thread Team Routines

Routines that affect and monitor thread teams in the current contention group.

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.
`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.
`LOGICAL(log) FUNCTION OMP_IN_PARALLEL()`	Returns .TRUE. if called within the dynamic extent of a parallel region executing in parallel; otherwise returns .FALSE..
`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.
`LOGICAL(log) FUNCTION OMP_GET_DYNAMIC()`	Returns .TRUE. if dynamic thread adjustment is enabled, otherwise returns .FALSE..
`LOGICAL(log) FUNCTION OMP_GET_CANCELLATION()`	Returns .TRUE. if cancellation is enabled, otherwise returns .FALSE.. This routine can be affected by the setting for environment variable `OMP_CANCELLATION`.
Deprecated `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.
Deprecated `LOGICAL FUNCTION OMP_GET_NESTED()`	Returns .TRUE. if nested parallelism is enabled, otherwise returns .FALSE..
`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 FUNCTION OMP_GET_THREAD_LIMIT()`	Returns the maximum number of simultaneously executing threads in an OpenMP program.
`INTEGER FUNCTION OMP_GET_SUPPORTED_ACTIVE_LEVELS()`	Returns the number of active levels of parallelism supported by the implementation.
`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` are 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_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.
`INTEGER FUNCTION OMP_GET_ACTIVE_LEVEL()`	Returns the number of nested, active parallel regions enclosing the task that contains the call.

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

Thread Affinity Routines

Routines that affect and access thread affinity policies that are in effect.

Function	Description
`INTEGER(KIND=OMP_PROC_BIND_KIND) OMP_GET_PROC_BIND()`	Returns the currently active thread affinity policy, which can be initialized by the 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 negative or 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 FUNCTION OMP_GET_PARTITION_NUM_PLACES()`	Returns the number of places in the place partition of the innermost implicit task.
`SUBROUTINE OMP_GET_PARTITION_PLACE_NUMS(place_nums)` `INTEGER(int) place_nums(*)`	Returns the list of place numbers corresponding to the places in the place-partition-var ICV of the innermost implicit task. The array `place_nums` must be sufficiently large to contain `OMP_GET_PARTITION_NUM_PLACES()` elements.
`SUBROUTINE OMP_SET_AFFINITY_FORMAT(format)` `CHARACTER(LEN=*),INTENT(IN) :: format`	Sets the affinity format to be used on the device by setting the value of the affinity-format-var ICV.
`INTEGER FUNCTION OMP_GET_AFFINITY_FORMAT(buffer)` `CHARACTER(LEN=*),INTENT(OUT) :: buffer`	Returns the value of the affinity-format-var ICV on the device.
`SUBROUTINE OMP_DISPLAY_AFFINITY(format)` `CHARACTER(LEN=*),INTENT(IN) :: format`	Prints the OpenMP thread affinity information using the format specification provided.
`INTEGER FUNCTION OMP_CAPTURE_AFFINITY(buffer, format)` `CHARACTER(LEN=),INTENT(OUT) :: buffer` `CHARACTER(LEN=),INTENT(IN) :: format`	Prints the OpenMP thread affinity information into a buffer using the format specification provided.

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

Teams Region Routines

Routines that affect and monitor the league of teams that may execute a TEAMS region.

Function	Description
`INTEGER(int) FUNCTION OMP_GET_NUM_TEAMS()`	Returns the number of initial teams in the current TEAMS region.
`INTEGER(int) FUNCTION OMP_GET_TEAM_NUM()`	Returns the team number of the calling thread.
`SUBROUTINE OMP_SET_NUM_TEAMS(num_teams)` `INTEGER num_teams`	Affects the number of threads to be used for subsequent TEAMS regions that do not specify a `NUM_TEAMS` clause.
`INTEGER FUNCTION OMP_GET_MAX_TEAMS()`	Returns an upper bound on the number of teams that could be created by a TEAMS construct without a `NUM_TEAMS` clause that is encountered after execution returns from this routine.
`SUBROUTINE OMP_SET_TEAMS_THREAD_LIMIT(thread_limit)` `INTEGER thread_limit`	Defines the maximum number of OpenMP threads that can participate in each contention group created by a TEAMS construct.
`INTEGER FUNCTION OMP_GET_TEAMS_THREAD_LIMIT()`	Returns the maximum number of OpenMP threads available to participate in each contention group created by a TEAMS construct.

Tasking Routines

Routines that pertain to OpenMP explicit tasks.

Function	Description
`INTEGER(int) FUNCTION OMP_GET_MAX_TASK_PRIORITY()`	Returns the maximum value that can be specified in the PRIORITY clause.
`LOGICAL(log) FUNCTION OMP_IN_EXPLICIT_TASK()`	Returns .TRUE. if called within an explicit task region; otherwise returns .FALSE..
`LOGICAL(log) FUNCTION OMP_IN_FINAL()`	Returns .TRUE. if called within a final task region; otherwise returns .FALSE..

Resource Relinquishing Routines

Routines that relinquish resources used by the OpenMP runtime. These routines are only effective on the host device.

Function	Description
`INTEGER FUNCTION OMP_PAUSE_RESOURCE(kind, device_num)` `INTEGER (OMP_PAUSE_RESOURCE_KIND) kind` `INTEGER device_num`	Allows the runtime to relinquish resources used by OpenMP on the specified device. The routine returns zero in case of success, and non-zero otherwise.
`INTEGER FUNCTION OMP_PAUSE_RESOURCE_ALL(kind)` `INTEGER (OMP_PAUSE_RESOURCE_KIND) kind`	Allows the runtime to relinquish resources used by OpenMP on all devices. The routine returns zero in case of success, and non-zero otherwise.

Function

Description

INTEGER FUNCTION OMP_PAUSE_RESOURCE(kind, device_num)

INTEGER (OMP_PAUSE_RESOURCE_KIND) kind

INTEGER device_num

Allows the runtime to relinquish resources used by OpenMP on the specified device. The routine returns zero in case of success, and non-zero otherwise.

INTEGER FUNCTION OMP_PAUSE_RESOURCE_ALL(kind)

INTEGER (OMP_PAUSE_RESOURCE_KIND) kind

Allows the runtime to relinquish resources used by OpenMP on all devices. The routine returns zero in case of success, and non-zero otherwise.

Device Information Routines

Routines that pertain to the set of devices that are accessible to an OpenMP program.

Function	Description
`INTEGER(int) FUNCTION OMP_GET_NUM_PROCS()`	Returns the number of processors available to the program.
`SUBROUTINE OMP_SET_DEFAULT_DEVICE(device_number)` `INTEGER(int) device_number`	Sets the default device number.
`INTEGER(int) FUNCTION OMP_GET_DEFAULT_DEVICE()`	Returns the default device number.
`INTEGER(int) FUNCTION OMP_GET_NUM_DEVICES()`	Returns the number of target devices.
`INTEGER FUNCTION OMP_GET_DEVICE_NUM()`	Returns the device number of the device on which the calling thread is executing.
`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.

Device Memory Routines

Function	Description
`TYPE(c_ptr) FUNCTION omp_target_alloc (size, device_num)` `USE, INTRINSIC :: ISO_C_BINDING` `INTEGER(c_size_t) :: size` `INTEGER(c_int) :: device_num`	Returns the device address of a storage location that is `size` bytes in length. If the allocation request cannot be satisfied, a null address is returned. The allocation occurs on the device specified by `device_num`.
`SUBROUTINE omp_target_free (device_ptr, device_num)` `USE, INTRINISIC :: ISO_C_BINDING` `TYPE (c_ptr) :: device_ptr` `INTEGER(c_int) :: device_num`	Deallocates the previously allocated memory allocation pointed to by `device_ptr` on the device specified by `device_num`.

Function

Description

TYPE(c_ptr) FUNCTION omp_target_alloc (size, device_num)

USE, INTRINSIC :: ISO_C_BINDING

INTEGER(c_size_t) :: size

INTEGER(c_int) :: device_num

Returns the device address of a storage location that is size bytes in length. If the allocation request cannot be satisfied, a null address is returned. The allocation occurs on the device specified by device_num.

SUBROUTINE omp_target_free (device_ptr, device_num)

USE, INTRINISIC :: ISO_C_BINDING

TYPE (c_ptr) :: device_ptr

INTEGER(c_int) :: device_num

Deallocates the previously allocated memory allocation pointed to by device_ptr on the device specified by device_num.

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 to the unlocked state.
`SUBROUTINE OMP_INIT_NEST_LOCK(nvar)` `INTEGER(KIND=OMP_NEST_LOCK_KIND)nvar`	Initializes the nested lock to the unlocked state. The nesting count for the nested lock is set to zero.
`SUBROUTINE OMP_INIT_LOCK_WITH_HINT(svar, hint)` `INTEGER (KIND=OMP_LOCK_KIND)svar` `INTEGER (KIND=OMP_SYNC_HINT_KIND)hint`	Initializes the lock to the unlocked state, optionally choosing a specific lock implementation based on `hint`.
`SUBROUTINE OMP_INIT_NEST_LOCK_WITH_HINT(nvar, hint)` `INTEGER (KIND=OMP_NEST_LOCK_KIND)nvar` `INTEGER (KIND=OMP_SYNC_HINT_KIND)hint`	Initializes the nested lock to the unlocked state, optionally choosing a specific lock implementation based on `hint`. The nesting count for the nested lock is set to zero.
`SUBROUTINE OMP_DESTROY_LOCK(svar)` `INTEGER(KIND=OMP_LOCK_KIND)svar`	Changes the state of the lock to uninitialized.
`SUBROUTINE OMP_DESTROY_NEST_LOCK(nvar)` `INTEGER(KIND=OMP_NEST_LOCK_KIND)nvar`	Changes the state of the nested lock to uninitialized.
`SUBROUTINE OMP_SET_LOCK(svar)` `INTEGER(KIND=OMP_LOCK_KIND)svar`	Forces the executing thread to wait until the lock is available. The thread is granted ownership of the lock when it becomes available. The lock must be initialized.
`SUBROUTINE OMP_SET_NEST_LOCK(nvar)` `INTEGER(KIND=OMP_NEST_LOCK_KIND)nvar`	Forces the executing thread to wait until the nested lock is available. If the thread already owns the lock, then the lock nesting count is incremented. 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. The behavior is undefined if the executing thread does not own the lock.
`SUBROUTINE OMP_UNSET_NEST_LOCK(nvar)` `INTEGER(KIND=OMP_NEST_LOCK_KIND)nvar`	Decrements the nesting count for the nested lock and releases the executing thread from ownership of the nested lock if the resulting nesting count is zero. Behavior is undefined if the executing thread does not own the nested lock.
`LOGICAL(log) OMP_TEST_LOCK(svar)` `INTEGER(KIND=OMP_LOCK_KIND)svar`	Attempts to set the lock. If successful, returns .TRUE., otherwise returns .FALSE.. The lock must be initialized.
`INTEGER(int) OMP_TEST_NEST_LOCK(nvar)` `INTEGER(KIND=OMP_NEST_LOCK_KIND)nvar`	Attempts to set the nested lock. If successful, returns the nesting count, otherwise returns zero.

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_sync_hint_kind), parameter :: omp_sync_hint_none           = 0
integer (omp_sync_hint_kind), parameter :: omp_sync_hint_uncontended    = 1
integer (omp_sync_hint_kind), parameter :: omp_sync_hint_contended      = 2
integer (omp_sync_hint_kind), parameter :: omp_sync_hint_nonspeculative = 4
integer (omp_sync_hint_kind), parameter :: omp_sync_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_sync_hint_none with any other hint is equivalent to specifying the other hint. The following restrictions apply to combined hints:

Hints omp_sync_hint_uncontended and omp_sync_hint_contended cannot be combined.
Hints omp_sync_hint_nonspeculative and omp_sync_hint_nonspeculative cannot be combined.

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.

Event Routines

Function	Description
`SUBROUTINE OMP_FULFILL_EVENT(event)` `INTEGER(OMP_EVENT_HANDLE_KIND) event`	Fulfills the event associated with the event handle `event` and destroys the event.

Function

Description

SUBROUTINE OMP_FULFILL_EVENT(event)

INTEGER(OMP_EVENT_HANDLE_KIND) event

Fulfills the event associated with the event handle event and destroys the event.

Memory Management Routines

Function	Description
`FUNCTION omp_init_allocator(memspace, ntraits, traits)` `INTEGER (KIND=omp_allocator_handle_kind) omp_init_allocator` `INTEGER (KIND=omp_memspace_handle_kind),INTENT(IN) :: memspace` `INTEGER,INTENT(IN) :: ntraits` `TYPE(omp_alloctrait),INTENT(IN) :: traits(*)`	Initialize an allocator and associate it with a memory space, returning an allocator handle. The `memspace` argument must be one of the predefined memory spaces defined in OpenMP Memory Space Allocators. The `ntraits` argument specifies the number of traits in the traits array argument. If there are fewer traits than specified by `ntraits`, the behavior is undefined. A `REQUIRES` directive specifying `dynamic_allocators` must appear in the same compilation unit of a target region that calls this function.
`SUBROUTINE omp_destroy_allocator (allocator)` `INTEGER(KIND=omp_allocator_handle_kind),INTENT(IN) :: allocator`	Releases all resources used by the allocator handle argument. The allocator argument must not be a handle for a predefined allocator. A `REQUIRES` directive specifying `dynamic_allocators` must appear in the same compilation unit of a target region that calls this function.
`SUBROUTINE omp_set_default_allocator (allocator)` `INTEGER(KIND=omp_allocator_handle_kind) :: allocator`	Sets the default memory allocator used for memory allocations resulting from `ALLOCATE` clauses and directives that do not specify an allocator. The allocator argument must be a valid allocator.
`FUNCTION omp_get_default_allocator ()` `INTEGER(KIND=omp_allocator_handle_kind) :: omp_get_default_allocator`	Returns the allocator handle of the allocator to be used for allocations resulting from `ALLOCATE` clauses and directives that do not specify an allocator.
`TYPE(c_ptr) FUNCTION omp_alloc (size, allocator) bind (c)` `USE, INTRINSIC ISO_C_BINDING` `INTEGER(c_size_t) VALUE :: size` `INTEGER(omp_allocator_handle_kind), value :: allocator`	Requests a memory allocation of `size` bytes from the specified memory allocator. The `allocator` argument must be an integer constant expression that evaluates to the value of one of the predefined memory allocator values. If `allocator` is `OMP_NULL_ALLOCATOR`, the allocator used is the allocator specified by the ICV def-allocator-var of the binding implicit task. A pointer to the first word allocated is returned if the allocation is successful; otherwise, the behavior is that specified for the fallback trait of the allocator. If `size` is zero, `C_NULL_PTR` (Fortran) or `NULL (C)` is returned. Allocated memory is byte aligned to at least the maximum of the alignment required by `malloc` and the alignment trait of the allocator. Calls to `omp_alloc` that appear in target regions may not pass `OMP_NULL_ALLOCATOR` as the allocator argument, unless a `REQUIRES` directive specifying `DYNAMIC_ALLOCATORS` appears in the same compilation unit.
`TYPE(c_ptr) FUNCTION omp_aligned_alloc (alignment, size, allocator) bind (c)` `USE, INTRINSIC ISO_C_BINDING` `INTEGER(c_size_t) VALUE :: alignment, size` `INTEGER(omp_allocator_handle_kind), value :: allocator`	Requests a memory allocation of `size` bytes from the specified memory allocator. `alignment` must be a power of two, and `size` must be a multiple of alignment. The `allocator` argument must be an integer constant expression that evaluates to the value of one of the predefined memory allocator values. If `allocator` is `OMP_NULL_ALLOCATOR`, the allocator used is the allocator specified by the ICV def-allocator-var of the binding implicit task. A pointer to the first word allocated is returned if the allocation is successful; otherwise, the behavior is that specified for the fallback trait of the allocator. If `size` is zero, `C_NULL_PTR` (Fortran) or `NULL (C)` is returned. Allocated memory is byte aligned to at least the maximum of the alignment required by malloc, the alignment trait of the allocator, and the value specified for the alignment argument. Calls to `omp_alloc` that appear in target regions may not pass `OMP_NULL_ALLOCATOR` as the allocator argument, unless a `REQUIRES` directive specifying `DYNAMIC_ALLOCATORS` appears in the same compilation unit.
`TYPE(c_ptr) FUNCTION omp_calloc (nmemb, size, allocator) bind (c)` `USE, INTRINSIC :: ISO_C_BINDING` `INTEGER(c_size_t) value :: nmemb, size` `INTEGER(omp_allocator_handle_t), value :: allocator`	Requests a zero initialized memory allocation of `size` bytes from the specified memory allocator. The `allocator` argument must be an integer constant expression whose value is one of the predefined memory allocators. If `omp_calloc` is called from a `TARGET` region, the value of allocator must not be `OMP_NULL_ALLOCATOR` unless `DYNAMIC_ALLOCATORS` appears in a `REQUIRES` directive in the same compilation unit as the call. If `OMP_NULL_ALLOCATOR` is specified, the allocator used is the allocator specified by the def-allocator-var ICV of the binding implicit task. The allocation is an array of `nmemb` elements; each element is `size` bytes. `allocator` specifies the memory allocator to use. The allocated memory is initialized to zero. If the request is unsuccessful, the behavior is that specified by the `FALLBACK` trait of the allocator. The allocation is aligned to at least the maximum of the alignment required by `malloc` and the alignment trait of the allocator. If either `nmemb` or `size` has the value 0, the value `NULL (C)` or `C_NULL_PTR` (Fortran) is returned.

Function

Description

FUNCTION omp_init_allocator(memspace, ntraits, traits)

INTEGER (KIND=omp_allocator_handle_kind) omp_init_allocator

INTEGER (KIND=omp_memspace_handle_kind),INTENT(IN) :: memspace

INTEGER,INTENT(IN) :: ntraits

TYPE(omp_alloctrait),INTENT(IN) :: traits(*)

Initialize an allocator and associate it with a memory space, returning an allocator handle. The memspace argument must be one of the predefined memory spaces defined in OpenMP Memory Space Allocators. The ntraits argument specifies the number of traits in the traits array argument. If there are fewer traits than specified by ntraits, the behavior is undefined. A REQUIRES directive specifying dynamic_allocators must appear in the same compilation unit of a target region that calls this function.

SUBROUTINE omp_destroy_allocator (allocator)

INTEGER(KIND=omp_allocator_handle_kind),INTENT(IN) :: allocator

Releases all resources used by the allocator handle argument. The allocator argument must not be a handle for a predefined allocator. A REQUIRES directive specifying dynamic_allocators must appear in the same compilation unit of a target region that calls this function.

SUBROUTINE omp_set_default_allocator (allocator)

INTEGER(KIND=omp_allocator_handle_kind) :: allocator

Sets the default memory allocator used for memory allocations resulting from ALLOCATE clauses and directives that do not specify an allocator. The allocator argument must be a valid allocator.

FUNCTION omp_get_default_allocator ()

INTEGER(KIND=omp_allocator_handle_kind) :: omp_get_default_allocator

Returns the allocator handle of the allocator to be used for allocations resulting from ALLOCATE clauses and directives that do not specify an allocator.

TYPE(c_ptr) FUNCTION omp_alloc (size, allocator) bind (c)

USE, INTRINSIC ISO_C_BINDING

INTEGER(c_size_t) VALUE :: size

INTEGER(omp_allocator_handle_kind), value :: allocator

Requests a memory allocation of size bytes from the specified memory allocator.

The allocator argument must be an integer constant expression that evaluates to the value of one of the predefined memory allocator values. If allocator is OMP_NULL_ALLOCATOR, the allocator used is the allocator specified by the ICV def-allocator-var of the binding implicit task.

A pointer to the first word allocated is returned if the allocation is successful; otherwise, the behavior is that specified for the fallback trait of the allocator. If size is zero, C_NULL_PTR (Fortran) or NULL (C) is returned. Allocated memory is byte aligned to at least the maximum of the alignment required by malloc and the alignment trait of the allocator.

Calls to omp_alloc that appear in target regions may not pass OMP_NULL_ALLOCATOR as the allocator argument, unless a REQUIRES directive specifying DYNAMIC_ALLOCATORS appears in the same compilation unit.

TYPE(c_ptr) FUNCTION omp_aligned_alloc (alignment, size, allocator) bind (c)

USE, INTRINSIC ISO_C_BINDING

INTEGER(c_size_t) VALUE :: alignment, size

INTEGER(omp_allocator_handle_kind), value :: allocator

Requests a memory allocation of size bytes from the specified memory allocator. alignment must be a power of two, and size must be a multiple of alignment.

TYPE(c_ptr) FUNCTION omp_calloc (nmemb, size, allocator) bind (c)

USE, INTRINSIC :: ISO_C_BINDING

INTEGER(c_size_t) value :: nmemb, size

INTEGER(omp_allocator_handle_t), value :: allocator

Requests a zero initialized memory allocation of size bytes from the specified memory allocator.

The allocator argument must be an integer constant expression whose value is one of the predefined memory allocators. If omp_calloc is called from a TARGET region, the value of allocator must not be OMP_NULL_ALLOCATOR unless DYNAMIC_ALLOCATORS appears in a REQUIRES directive in the same compilation unit as the call. If OMP_NULL_ALLOCATOR is specified, the allocator used is the allocator specified by the def-allocator-var ICV of the binding implicit task.

The allocation is an array of nmemb elements; each element is size bytes. allocator specifies the memory allocator to use. The allocated memory is initialized to zero. If the request is unsuccessful, the behavior is that specified by the FALLBACK trait of the allocator. The allocation is aligned to at least the maximum of the alignment required by malloc and the alignment trait of the allocator.

If either nmemb or size has the value 0, the value NULL (C) or C_NULL_PTR (Fortran) is returned.

The derived type omp_allocator is defined in OMP_LIB.MOD and is used as the type of the traits argument to the omp_init_allocator function.

type omp_alloctrait
  integer(kind=omp_alloctrait_key_kind) :: key
  integer(kind=omp_alloctrait_val_kind) :: value
end type omp_alloctrait

The following parameter constants are defined in OMP_LIB.MOD and can be used to specify allocator trait keys in a derived type of type omp_alloctrait.

integer(omp_alloctrait_key_kind), parameter :: omp_atk_sync_hint  = 1
integer(omp_alloctrait_key_kind), parameter :: omp_atk_alignment  = 2
integer(omp_alloctrait_key_kind), parameter :: omp_atk_access     = 3
integer(omp_alloctrait_key_kind), parameter :: omp_atk_pool_size  = 4
integer(omp_alloctrait_key_kind), parameter :: omp_atk_fallback   = 5
integer(omp_alloctrait_key_kind), parameter :: omp_atk_fb_data    = 6
integer(omp_alloctrait_key_kind), parameter :: omp_atk_atk_pinned = 7
integer(omp_alloctrait_key_kind), parameter :: omp_atk_partition  = 8

The following parameter constants are defined in OMP_LIB.MOD and can be used to set allocator trait values in a derived type of type omp_alloctrait.

integer(omp_alloctrait_val_kind), parameter :: omp_atv_false           =  0 
integer(omp_alloctrait_val_kind), parameter :: omp_atv_true            =  1
integer(omp_alloctrait_val_kind), parameter :: omp_atv_default         =  2
integer(omp_alloctrait_val_kind), parameter :: omp_atv_contended       =  3
integer(omp_alloctrait_val_kind), parameter :: omp_atv_uncontended     =  4
integer(omp_alloctrait_val_kind), parameter :: omp_atv_sequential      =  5
integer(omp_alloctrait_val_kind), parameter :: omp_atv_private         =  6
integer(omp_alloctrait_val_kind), parameter :: omp_atv_all             =  7
integer(omp_alloctrait_val_kind), parameter :: omp_atv_thread          =  8
integer(omp_alloctrait_val_kind), parameter :: omp_atv_pteam           =  9 
integer(omp_alloctrait_val_kind), parameter :: omp_atv_cgroup          = 10
integer(omp_alloctrait_val_kind), parameter :: omp_atv_default_mem_fb  = 11
integer(omp_alloctrait_val_kind), parameter :: omp_atv_null_fb         = 12
integer(omp_alloctrait_val_kind), parameter :: omp_atv_abort_fb        = 13
integer(omp_alloctrait_val_kind), parameter :: omp_atv_allocator_fb    = 14
integer(omp_alloctrait_val_kind), parameter :: omp_atv_environment     = 15
integer(omp_alloctrait_val_kind), parameter :: omp_atv_nearest         = 16
integer(omp_alloctrait_val_kind), parameter :: omp_atv_blocked         = 17
integer(omp_alloctrait_val_kind), parameter :: omp_atv_interleaved     = 18

Tool Control Routines

Function	Description
`INTEGER FUNCTION OMP_CONTROL_TOOL(command, modifier)` `INTEGER (kind=omp_control_tool_kind) command` `INTEGER modifier`	Enables a program to pass commands to an active tool.

Function

Description

INTEGER FUNCTION OMP_CONTROL_TOOL(command, modifier)

INTEGER (kind=omp_control_tool_kind) command

INTEGER modifier

Enables a program to pass commands to an active tool.

Environment Display Routines

Function	Description
`SUBROUTINE OMP_DISPLAY_ENV(verbose)` `LOGICAL,INTENT(IN) :: verbose`	Displays the OpenMP version number and the initial values of ICVs associated with the environment variables.

Function

Description

SUBROUTINE OMP_DISPLAY_ENV(verbose)

LOGICAL,INTENT(IN) :: verbose

Displays the OpenMP version number and the initial values of ICVs associated with the environment variables.

Device Runtime Routines Available on GPU

The following device runtime routines are available on CPU and GPU.

OMP_GET_DEVICE_NUM
OMP_GET_MAX_THREADS
OMP_GET_NUM_DEVICES
OMP_GET_NUM_PROCS
OMP_GET_NUM_TEAMS
OMP_GET_NUM_THREADS
OMP_GET_TEAM_NUM
OMP_GET_TEAM_SIZE
OMP_GET_THREAD_LIMIT
OMP_GET_THREAD_NUM
OMP_IN_PARALLEL
OMP_IS_INITIAL_DEVICE

Parent topic: OpenMP* Library Support

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Guide and Reference

OpenMP* Runtime Library Routines

Thread Team Routines

Thread Affinity Routines

Teams Region Routines

Tasking Routines

Resource Relinquishing Routines

Device Information Routines

Device Memory Routines

Lock Routines

Timing Routines

Event Routines

Memory Management Routines

Tool Control Routines

Environment Display Routines

Device Runtime Routines Available on GPU

See Also