Run-Time Library Routines

Overview:

• The OpenMP standard defines an API for library calls that perform a variety of functions:

  • Query the number of threads/processors, set number of threads to use

  • General purpose locking routines (semaphores)

  • Portable wall clock timing routines

  • Set execution environment functions: nested parallelism, dynamic adjustment of threads.

• For C/C++, it may be necessary to specify the include file "omp.h".

• For the Lock routines/functions:

  • The lock variable must be accessed only through the locking routines

  • For Fortran, the lock variable should be of type integer and of a kind large enough to hold an address.

  • For C/C++, the lock variable must have type omp_lock_t or type omp_nest_lock_t, depending on the function being used.

• Implementation notes:

  • Your implementation may or may not support nested parallelism and/or dynamic threads. If nested parallelism is supported, it is often only nominal, in that a nested parallel region may only have one thread.

  • Consult your implementation's documentation for details - or experiment and find out for yourself if you can't find it in the documentation.

OMP_SET_NUM_THREADS

Purpose:

• Sets the number of threads that will be used in the next parallel region. Must be a postive integer.

Format:

Fortran	SUBROUTINE OMP_SET_NUM_THREADS(scalar_integer_expression)
C/C++	#include <omp.h> void omp_set_num_threads(int num_threads)

Notes & Restrictions:

• The dynamic threads mechanism modifies the effect of this routine.
  • Enabled: specifies the maximum number of threads that can be used for any parallel region by the dynamic threads mechanism.
  • Disabled: specifies exact number of threads to use until next call to this routine.

• This routine can only be called from the serial portions of the code

• This call has precedence over the OMP_NUM_THREADS environment variable

OMP_GET_NUM_THREADS

Purpose:

• Returns the number of threads that are currently in the team executing the parallel region from which it is called.

Format:

Fortran	INTEGER FUNCTION OMP_GET_NUM_THREADS()
C/C++	#include <omp.h> int omp_get_num_threads(void)

Notes & Restrictions:

• If this call is made from a serial portion of the program, or a nested parallel region that is serialized, it will return 1.

• The default number of threads is implementation dependent.

OMP_GET_MAX_THREADS

Purpose:

• Returns the maximum value that can be returned by a call to the OMP_GET_NUM_THREADS function.

  Fortran	INTEGER FUNCTION OMP_GET_MAX_THREADS()
  C/C++	#include <omp.h> int omp_get_max_threads(void)

Notes & Restrictions:

• Generally reflects the number of threads as set by the OMP_NUM_THREADS environment variable or the OMP_SET_NUM_THREADS() library routine.

• May be called from both serial and parallel regions of code.

OMP_GET_THREAD_NUM

Purpose:

• Returns the thread number of the thread, within the team, making this call. This number will be between 0 and OMP_GET_NUM_THREADS-1. The master thread of the team is thread 0

Format:

Fortran	INTEGER FUNCTION OMP_GET_THREAD_NUM()
C/C++	#include <omp.h> int omp_get_thread_num(void)

Notes & Restrictions:

• If called from a nested parallel region, or a serial region, this function will return 0.

Examples:

• Example 1 is the correct way to determine the number of threads in a parallel region.
• Example 2 is incorrect - the TID variable must be PRIVATE

• Example 3 is incorrect - the OMP_GET_THREAD_NUM call is outside the parallel region

  Fortran - determining the number of threads in a parallel region Example 1: Correct PROGRAM HELLO INTEGER TID, OMP_GET_THREAD_NUM !$OMP PARALLEL PRIVATE(TID) TID = OMP_GET_THREAD_NUM() PRINT *, 'Hello World from thread = ', TID ... !$OMP END PARALLEL END Example 2: Incorrect PROGRAM HELLO INTEGER TID, OMP_GET_THREAD_NUM !$OMP PARALLEL TID = OMP_GET_THREAD_NUM() PRINT *, 'Hello World from thread = ', TID ... !$OMP END PARALLEL END Example 3: Incorrect PROGRAM HELLO INTEGER TID, OMP_GET_THREAD_NUM TID = OMP_GET_THREAD_NUM() PRINT *, 'Hello World from thread = ', TID !$OMP PARALLEL ... !$OMP END PARALLEL END

OMP_GET_THREAD_LIMIT

• New with OpenMP 3.0. Returns the maximum number of OpenMP threads available to a program.

Fortran	INTEGER FUNCTION OMP_GET_THREAD_LIMIT
C/C++	#include <omp.h> int omp_get_thread_limit (void)

Notes:

• Also see the OMP_THREAD_LIMIT environment variable.

OMP_GET_NUM_PROCS

Purpose:

• Returns the number of processors that are available to the program.

Format:

Fortran	INTEGER FUNCTION OMP_GET_NUM_PROCS()
C/C++	#include <omp.h> int omp_get_num_procs(void)

OMP_IN_PARALLEL

Purpose:

• May be called to determine if the section of code which is executing is parallel or not.

Format:

Fortran	LOGICAL FUNCTION OMP_IN_PARALLEL()
C/C++	#include <omp.h> int omp_in_parallel(void)

Notes & Restrictions:

• For Fortran, this function returns .TRUE. if it is called from the dynamic extent of a region executing in parallel, and .FALSE. otherwise. For C/C++, it will return a non-zero integer if parallel, and zero otherwise.

OMP_SET_DYNAMIC

Purpose:

• Enables or disables dynamic adjustment (by the run time system) of the number of threads available for execution of parallel regions.

Format:

Fortran	SUBROUTINE OMP_SET_DYNAMIC(scalar_logical_expression)
C/C++	#include <omp.h> void omp_set_dynamic(int dynamic_threads)

Notes & Restrictions:

• For Fortran, if called with .TRUE. then the number of threads available for subsequent parallel regions can be adjusted automatically by the run-time environment. If called with .FALSE., dynamic adjustment is disabled.

• For C/C++, if dynamic_threads evaluates to non-zero, then the mechanism is enabled, otherwise it is disabled.

• The OMP_SET_DYNAMIC subroutine has precedence over the OMP_DYNAMIC environment variable.

• The default setting is implementation dependent.

• Must be called from a serial section of the program.

OMP_GET_DYNAMIC

Purpose:

• Used to determine if dynamic thread adjustment is enabled or not.

Format:

Fortran	LOGICAL FUNCTION OMP_GET_DYNAMIC()
C/C++	#include <omp.h> int omp_get_dynamic(void)

Notes & Restrictions:

• For Fortran, this function returns .TRUE. if dynamic thread adjustment is enabled, and .FALSE. otherwise.

• For C/C++, non-zero will be returned if dynamic thread adjustment is enabled, and zero otherwise.

OMP_SET_NESTED

Purpose:

• Used to enable or disable nested parallelism.

Format:

Fortran	SUBROUTINE OMP_SET_NESTED(scalar_logical_expression)
C/C++	#include <omp.h> void omp_set_nested(int nested)

Notes & Restrictions:

• For Fortran, calling this function with .FALSE. will disable nested parallelism, and calling with .TRUE. will enable it.

• For C/C++, if nested evaluates to non-zero, nested parallelism is enabled; otherwise it is disabled.

• The default is for nested parallelism to be disabled.

• This call has precedence over the OMP_NESTED environment variable

OMP_GET_NESTED

Purpose:

• Used to determine if nested parallelism is enabled or not.

Format:

Fortran	LOGICAL FUNCTION OMP_GET_NESTED
C/C++	#include <omp.h> int omp_get_nested (void)

Notes & Restrictions:

• For Fortran, this function returns .TRUE. if nested parallelism is enabled, and .FALSE. otherwise.

• For C/C++, non-zero will be returned if nested parallelism is enabled, and zero otherwise.

OMP_SET_SCHEDULE
OMP_SET_SCHEDULE
OMP_GET_SCHEDULE
OMP_SET_MAX_ACTIVE_LEVELS
OMP_GET_MAX_ACTIVE_LEVELS

OMP_GET_LEVEL
OMP_GET_ANCESTOR_THREAD_NUM
OMP_GET_TEAM_SIZE
OMP_GET_ACTIVE_LEVEL
OMP_INIT_NEST_LOCK
OMP_DESTROY_NEST_LOCK
OMP_SET_NEST_LOCK
OMP_UNSET_NEST_LOCK
OMP_TEST_NEST_LOCK

• These routines are new with OpenMP 3.0. Please consult the most recent specs for details.

OMP_INIT_LOCK

Purpose:

• This subroutine initializes a lock associated with the lock variable.

Format:

Fortran	SUBROUTINE OMP_INIT_LOCK(var) SUBROUTINE OMP_INIT_NEST_LOCK(var)
C/C++	#include <omp.h> void omp_init_lock(omp_lock_t *lock) void omp_init_nest_lock(omp_nest_lock_t *lock)

Notes & Restrictions:

• The initial state is unlocked

• For Fortran, var must be an integer large enough to hold an address, such as INTEGER*8 on 64-bit systems.

OMP_DESTROY_LOCK

Purpose:

• This subroutine disassociates the given lock variable from any locks.

Format:

Fortran	SUBROUTINE OMP_DESTROY_LOCK(var) SUBROUTINE OMP_DESTROY_NEST_LOCK(var)
C/C++	#include <omp.h> void omp_destroy_lock(omp_lock_t *lock) void omp_destroy_nest__lock(omp_nest_lock_t *lock)

Notes & Restrictions:

• It is illegal to call this routine with a lock variable that is not initialized.

• For Fortran, var must be an integer large enough to hold an address, such as INTEGER*8 on 64-bit systems.

OMP_SET_LOCK

Purpose:

• This subroutine forces the executing thread to wait until the specified lock is available. A thread is granted ownership of a lock when it becomes available.

Format:

Fortran	SUBROUTINE OMP_SET_LOCK(var) SUBROUTINE OMP_SET_NEST_LOCK(var)
C/C++	#include <omp.h> void omp_set_lock(omp_lock_t *lock) void omp_set_nest__lock(omp_nest_lock_t *lock)

Notes & Restrictions:

• It is illegal to call this routine with a lock variable that is not initialized.

• For Fortran, var must be an integer large enough to hold an address, such as INTEGER*8 on 64-bit systems.

OMP_UNSET_LOCK

Purpose:

• This subroutine releases the lock from the executing subroutine.

Format:

Fortran	SUBROUTINE OMP_UNSET_LOCK(var) SUBROUTINE OMP_UNSET_NEST_LOCK(var)
C/C++	#include <omp.h> void omp_unset_lock(omp_lock_t *lock) void omp_unset_nest__lock(omp_nest_lock_t *lock)

Notes & Restrictions:

• It is illegal to call this routine with a lock variable that is not initialized.

• For Fortran, var must be an integer large enough to hold an address, such as INTEGER*8 on 64-bit systems.

OMP_TEST_LOCK

Purpose:

• This subroutine attempts to set a lock, but does not block if the lock is unavailable.

Format:

Fortran	SUBROUTINE OMP_TEST_LOCK(var) SUBROUTINE OMP_TEST_NEST_LOCK(var)
C/C++	#include <omp.h> int omp_test_lock(omp_lock_t *lock) int omp_test_nest__lock(omp_nest_lock_t *lock)

Notes & Restrictions:

• For Fortran, .TRUE. is returned if the lock was set successfully, otherwise .FALSE. is returned.

• For Fortran, var must be an integer large enough to hold an address, such as INTEGER*8 on 64-bit systems.

• For C/C++, non-zero is returned if the lock was set successfully, otherwise zero is returned.

• It is illegal to call this routine with a lock variable that is not initialized.

OMP_GET_WTIME

Purpose:

• Provides a portable wall clock timing routine

• Returns a double-precision floating point value equal to the number of elapsed seconds since some point in the past. Usually used in "pairs" with the value of the first call subtracted from the value of the second call to obtain the elapsed time for a block of code.

• Designed to be "per thread" times, and therefore may not be globally consistent across all threads in a team - depends upon what a thread is doing compared to other threads.

Format:

Fortran	DOUBLE PRECISION FUNCTION OMP_GET_WTIME()
C/C++	#include <omp.h> double omp_get_wtime(void)

Notes & Restrictions:

• Requires OpenMP version 2.0 support

OMP_GET_WTICK

Purpose:

• Provides a portable wall clock timing routine

• Returns a double-precision floating point value equal to the number of seconds between successive clock ticks.

Format:

Fortran	DOUBLE PRECISION FUNCTION OMP_GET_WTICK()
C/C++	#include <omp.h> double omp_get_wtick(void)

Notes & Restrictions:

• Requires OpenMP version 2.0 support