OpenMP* Runtime Library Routines

Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference

Download PDF

ID 767253

Date 3/22/2024

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-D3FC1F0B-DD99-4176-B9B5-56EEE72E81A7

View Details

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.

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 your source code by adding a statement similar to the following:

#include <omp.h>

The header files are provided in the ../include (Linux*) or ..\include (Windows*) directory of your compiler installation.

Thread Team Routines

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

Routine	Description
`void omp_set_num_threads(int nthreads)`	Sets the number of threads to use for subsequent parallel regions created by the calling thread.
`int omp_get_num_threads(void)`	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.
`int omp_get_max_threads(void)`	Returns the number of threads available to subsequent parallel regions created by the calling thread.
`int omp_get_thread_num(void)`	Returns the thread number of the calling thread, within the context of the current parallel region.
`int omp_in_parallel(void)`	Returns TRUE if called within the dynamic extent of a parallel region executing in parallel; otherwise returns FALSE.
`void omp_set_dynamic(int 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.
`int omp_get_dynamic(void)`	Returns TRUE if dynamic thread adjustment is enabled, otherwise returns FALSE.
`int omp_get_cancellation(void)`	Returns TRUE if cancellation is enabled, otherwise returns FALSE. This routine can be affected by the setting for environment variable `OMP_CANCELLATION`.
Deprecated `void omp_set_nested(int 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 `int omp_get_nested(void)`	Returns TRUE if nested parallelism is enabled, otherwise returns FALSE.
`void omp_set_schedule(omp_sched_t kind,int chunk_size)`	Determines the schedule of a worksharing loop that is applied when '`runtime`' is used as the schedule kind.
`void omp_get_schedule(omp_sched_kind kind,int chunk_size)`	Returns the schedule of a worksharing loop that is applied when the '`runtime`' schedule is used.
`int omp_get_thread_limit(void)`	Returns the maximum number of simultaneously executing threads in an OpenMP program.
`int omp_get_supported_active_levels(void)`	Returns the number of active levels of parallelism supported by the implementation.
`void omp_set_max_active_levels(int max_active_levels)`	Limits the number of nested active parallel regions. The value of `max_active_levels` must evaluate to a non-negative integer.
`int omp_get_max_active_levels(void)`	Returns the maximum number of nested active parallel regions.
`int omp_get_level(void)`	Returns the number of nested parallel regions (whether active or inactive) enclosing the task that contains the call, not including the implicit parallel region.
`int omp_get_ancestor_thread_num(int level)`	Returns the thread number of the ancestor at a given nest level of the current thread.
`int omp_get_team_size(int level)`	Returns the size of the thread team to which the ancestor or the current thread belongs for a given nested level.
`int omp_get_active_level(void)`	Returns the number of nested, active parallel regions enclosing the task that contains the call.

Thread Affinity Routines

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

Function	Description
`omp_proc_bind_t omp_get_proc_bind(void)`	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.
`int omp_get_num_places(void)`	Returns the number of places available to the execution environment in the place list of the initial task, usually threads, cores, or sockets.
`int omp_get_place_num_procs(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().
`void omp_get_place_proc_ids(int place_num, 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.The array `ids` must be sufficiently large to contain `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().
`int omp_get_place_num(void)`	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.
`int omp_get_partition_num_places(void)`	Returns the number of places in the place partition of the innermost implicit task.
`void omp_get_partition_place_nums(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.
`void omp_set_affinity_format(const char *format)`	Sets the affinity format to be used on the device by setting the value of the affinity-format-var ICV.
`size_t omp_get_affinity_format(char *buffer, size_t size)`	Returns the value of the affinity-format-var ICV on the device.
`void omp_display_affinity(const char *format)`	Prints the OpenMP thread affinity information using the format specification provided.
`size_t omp_capture_affinity(char buffer, size_t size, const char format)`	Prints the OpenMP thread affinity information into a buffer using the format specification provided.

Teams Region Routines

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

Function	Description
`int omp_get_num_teams(void)`	Returns the number of initial teams in the current teams region.
`int omp_get_team_num(void)`	Returns the initial team number of the calling thread.
`void omp_set_num_teams(int num_teams)`	Affects the number of threads to be used for subsequent teams regions that do not specify a `num_teams` clause.
`int omp_get_max_teams(void)`	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.
`void omp_set_teams_thread_limit(int thread_limit)`	Defines the maximum number of OpenMP threads that can participate in each contention group created by a teams construct.
`int omp_get_teams_thread_limit(void)`	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
`int omp_get_max_task_priority(void)`	Returns the maximum value that can be specified in the priority clause.
`int omp_in_explicit_task(void)`	Returns TRUE if called within an explicit task region; otherwise returns FALSE.
`int omp_in_final(void)`	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
`int omp_pause_resource(omp_pause_resource_t kind, int 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.
`int omp_pause_resource_all(omp_pause_resource_t 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
`int omp_get_num_procs(void)`	Returns the number of processors available to the program.
`void omp_set_default_device(int device_number)`	Sets the default device number.
`int omp_get_default_device(void)`	Returns the default device number.
`int omp_get_num_devices(void)`	Returns the number of target devices.
`int omp_get_device_num(void)`	Returns the device number of the device on which the calling thread is executing.
`int omp_is_initial_device(void)`	Returns TRUE if the current task is running on the host device; otherwise, FALSE.
`int omp_get_initial_device(void)`	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

Routines that support allocation of memory and management of pointers in the data environments of target devices.

Routine	Description
`void *omp_target_alloc(size_t size, int device_num)`	Allocates memory in a device data environment and returns a device pointer to that memory.
`void omp_target_free(void *device_ptr, int device_num)`	Frees device memory that was allocated by the `omp_target_alloc`.
`int omp_target_is_present(const void *ptr, int device_num)`	Returns TRUE if `device_num` refers to the host device or if `ptr` refers to storage that has corresponding storage in the device data environment of `device_num`. Otherwise, it returns FALSE.
`int omp_target_is_accessible(const void *ptr, size_t size, int device_num)`	Returns TRUE if the storage of size bytes starting at the address given by `ptr` is accessible from device `device_num`. Otherwise, it returns FALSE.
`int omp_target_memcpy(void dst, const void src, size_t length, size_t dst_offset, size_t src_offset, int dst_device_num, int src_device_num)`	This routine copies `length` bytes of memory at offset `src _offset` from `src` in the device data environment of device `src_device_num` to `dst`, starting at offset `dst_offset` in the device data environment of the device specified by `dst_device_num`. Returns zero on success and a non-zero value on failure. Use `omp_get_initial_device` to return the device number you can use to reference the host device and host device data environment. This routine includes a task scheduling point. The effect of this routine is unspecified when it is called from within a target region.
`int omp_target_memcpy_rect(void dst, const void src, size_t element_size, int num_dims, const size_t volume, const size_t dst_offsets, const size_t src_offsets, const size_t dst_dimensions, const size_t *src_dimensions, int dst_device_num, int src_device_num)`	This routine copies a rectangular `subvolume` of `src`, in the device data environment of the device specified by `src_device_num`, to `dst`, in the device data environment of the device specified by `dst_device_num`. Specify the volume in terms of the size of an element, the number of its dimensions, and constant arrays of length `num_dims`. The maximum number of dimensions supported is three or more. The volume array specifies the length, in number of elements, to copy in each dimension from `src` to `dst`. The `dst_offsets` and `src_offsets` parameters specify the number of elements from the origin of `dst` and `src`, in elements. The `dst_dimensions` and `src_dimensions` parameters specify the length of each dimension of `dst` and `src`. The routine returns zero if successful. Otherwise, it returns a non-zero value. If both `dst` and `src` are NULL pointers, the routine returns the number of dimensions supported by the implementation for the specified device numbers. You can use the device number returned by `omp_get_initial_device` to reference the host device and host device data environment. This routine contains a task scheduling point. The effect of this routine is unspecified when called from within a target region.
`int omp_target_associate_ptr(const void host_ptr, const void device_ptr, size_t size, size_t device_offset, int device_num)`	Maps a device pointer, which might be returned by `omp_target_alloc`, to a host pointer.
`int omp_target_disassociate_ptr(const void *ptr, int device_num)`	Removes the associated pointer for a given device from a host pointer.
`void omp_get_mapped_ptr(const void ptr, int device_num)`	Returns the device pointer that is associated with a host pointer for a given device.

Lock Routines

Use these routines to affect OpenMP locks.

Function	Description
`void omp_init_lock(omp_lock_t *lock)`	Initializes the lock to the unlocked state.
`void omp_init_nest_lock(omp_nest_lock_t *lock)`	Initializes the nested lock to the unlocked state. The nesting count for the nested lock is set to zero.
`void omp_init_lock_with_hint(omp_lock_t *lock, omp_sync_hint_t hint)`	Initializes the lock to the unlocked state, optionally choosing a specific lock implementation based on `hint`. See the OpenMP specification for the available hints.
`void omp_init_nest_lock_with_hint(omp_nest_lock_t *lock, omp_sync_hint_t 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. See the OpenMP specification for the available hints.
`void omp_destroy_lock(omp_lock_t *lock)`	Changes the state of the lock to uninitialized.
`void omp_destroy_nest_lock(omp_nest_lock_t *lock)`	Changes the state of the nested lock to uninitialized.
`void omp_set_lock(omp_lock_t *lock)`	Forces the executing thread to wait until the lock is available. The thread is granted ownership of the lock when it becomes available.
`void omp_set_nest_lock(omp_nest_lock_t *lock)`	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.
`void omp_unset_lock(omp_lock_t *lock)`	Releases the executing thread from ownership of the lock. The behavior is undefined if the executing thread does not own the lock.
`void omp_unset_nest_lock(omp_nest_lock_t *lock)`	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.
`int omp_test_lock(omp_lock_t *lock)`	Attempts to set the lock. If successful, returns TRUE, otherwise returns FALSE.
`int omp_test_nest_lock(omp_nest_lock_t *lock)`	Attempts to set the nested lock. If successful, returns the nesting count, otherwise returns zero.

Timing Routines

Function	Description
`double omp_get_wtime(void)`	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.
`double omp_get_wtick(void)`	Returns a double precision value equal to the number of seconds between successive clock ticks.

Event Routines

Function	Description
`void omp_fulfill_event(omp_event_handle_t event)`	Fulfills the event associated with the event handle `event` and destroys the event.

Interoperability Routines

Function	Description
`int omp_get_num_interop_properties(const omp_interop_t interop)`	Returns the number of implementation-defined properties available for interop. The total number of properties available for interop is the returned value minus `omp_ipr_first`.
`omp_intptr_t omp_get_interop_int(const omp_interop_t interop, omp_interop_property_t property_id, int *ret_code)`	Returns the requested integer property, if available, and zero if an error occurs or no value is available.
`void omp_get_interop_ptr(const omp_interop_t interop, omp_interop_property_t property_id, int ret_code)`	Returns the requested pointer property, if available, and NULL if an error occurs or no value is available.
`const char omp_get_interop_str(const omp_interop_t interop, omp_interop_property_t property_id, int ret_code)`	Returns the requested string property as a C string, if available, and NULL if an error occurs or no value is available.
`const char *omp_get_interop_name(const omp_interop_t interop, omp_interop_property_t property_id)`	Returns the name of the property identified by `property_id` as a C string.
`const char *omp_get_interop_type_desc(const omp_interop_t interop, omp_interop_property_t property_id)`	Returns a C string that describes the type of the property identified by `property_id` in human-readable form.
`const char *omp_get_interop_rc_desc(const omp_interop_t interop, omp_interop_rc_t ret_code)`	Returns a C string that describes the return code `ret_code` in human-readable form.

Memory Management Routines

Function	Description
`omp_allocator_handle_t omp_init_allocator(omp_memspace_handle_t memspace, int ntraits, const omp_alloctrait_t traits[])`	Creates a new allocator that is associated with the `memspace` memory space and returns a handle to it.
`void omp_destroy_allocator(omp_allocator_handle_t allocator)`	Releases all resources used to implement the allocator handle.
`void omp_set_default_allocator(omp_allocator_handle_t allocator)`	Sets the default memory allocator to be used by allocation calls, allocate directives and allocate clauses that do not specify an allocator.
`omp_allocator_handle_t omp_get_default_allocator(void)`	Returns a handle to the memory allocator to be used by allocation calls, allocate directives and allocate clauses that do not specify an allocator.
`void *omp_alloc(size_t size, omp_allocator_handle_t allocator)`	Requests a memory allocation of size bytes from the specified memory allocator.
`void *omp_aligned_alloc(size_t alignment, size_t size, omp_allocator_handle_t allocator)`	Requests a memory allocation of `size` bytes from the specified memory allocator. Memory allocated by `omp_aligned_alloc` will be byte-aligned to at least the maximum of the alignment required by malloc, the alignment trait of the allocator and the alignment argument value.
`void omp_free(void *ptr, omp_allocator_handle_t allocator)`	Deallocates the memory to which `ptr` points. The `ptr` argument must have been returned by an OpenMP allocation routine.
`void *omp_calloc(size_t nmemb, size_t size, omp_allocator_handle_t allocator)`	Requests a memory allocation from the specified memory allocator for an array of `nmemb` elements each of which has a size of `size` bytes.
`void *omp_aligned_calloc(size_t alignment, size_t nmemb, size_t size, omp_allocator_handle_t allocator)`	Requests a memory allocation from the specified memory allocator for an array of `nmemb` elements each of which has a size of `size` bytes. Memory allocated by `omp_aligned_calloc` will be byte-aligned to at least the maximum of the alignment required by malloc, the alignment trait of the allocator and the alignment argument value.
`void omp_realloc(void ptr, size_t size, omp_allocator_handle_t allocator, omp_allocator_handle_t free_allocator)`	Deallocates the memory to which `ptr` points and requests a new memory allocation of `size` bytes from the specified memory allocator. Upon success it returns a pointer to the allocated memory and the contents of the new object shall be the same as that of the old object prior to deallocation up to the minimum size of old allocated size and `size` argument.

Tool Control Routines

Function	Description
`int omp_control_tool(int command, int modifier, void *arg)`	Enables a program to pass commands to an active tool.

Environment Display Routines

Function	Description
`void omp_display_env(int 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

Intel® oneAPI DPC++/C++ Compiler 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

Interoperability Routines

Memory Management Routines

Tool Control Routines

Environment Display Routines

Device Runtime Routines Available on GPU

See Also