HOME
| OPENMP API Specification: Version 5.1 November 2020

3.9  Lock Routines

The OpenMP runtime library includes a set of general-purpose lock routines that can be used for synchronization. These general-purpose lock routines operate on OpenMP locks that are represented by OpenMP lock variables. OpenMP lock variables must be accessed only through the routines described in this section; programs that otherwise access OpenMP lock variables are non-conforming.

An OpenMP lock can be in one of the following states: uninitialized; unlocked; or locked. If a lock is in the unlocked state, a task can set the lock, which changes its state to locked. The task that sets the lock is then said to own the lock. A task that owns a lock can unset that lock, returning it to the unlocked state. A program in which a task unsets a lock that is owned by another task is non-conforming.

Two types of locks are supported: simple locks and nestable locks. A nestable lock can be set multiple times by the same task before being unset; a simple lock cannot be set if it is already owned by the task trying to set it. Simple lock variables are associated with simple locks and can only be passed to simple lock routines. Nestable lock variables are associated with nestable locks and can only be passed to nestable lock routines.

Each type of lock can also have a synchronization hint that contains information about the intended usage of the lock by the application code. The effect of the hint is implementation defined. An OpenMP implementation can use this hint to select a usage-specific lock, but hints do not change the mutual exclusion semantics of locks. A conforming implementation can safely ignore the hint.

Constraints on the state and ownership of the lock accessed by each of the lock routines are described with the routine. If these constraints are not met, the behavior of the routine is unspecified.

The OpenMP lock routines access a lock variable such that they always read and update the most current value of the lock variable. An OpenMP program does not need to include explicit flush directives to ensure that the lock variable’s value is consistent among different tasks.

Binding The binding thread set for all lock routine regions is all threads in the contention group. As a consequence, for each OpenMP lock, the lock routine effects relate to all tasks that call the routines, without regard to which teams in the contention group the threads that are executing the tasks belong.

Simple Lock Routines

SVG-Viewer needed.

The type omp_lock_t represents a simple lock. For the following routines, a simple lock variable must be of omp_lock_t type. All simple lock routines require an argument that is a pointer to a variable of type omp_lock_t.

SVG-Viewer needed.

SVG-Viewer needed.

For the following routines, a simple lock variable must be an integer variable of kind=omp_lock_kind.

SVG-Viewer needed.

The simple lock routines are as follows:

Nestable Lock Routines

SVG-Viewer needed.

The type omp_nest_lock_t represents a nestable lock. For the following routines, a nestable lock variable must be of omp_nest_lock_t type. All nestable lock routines require an argument that is a pointer to a variable of type omp_nest_lock_t.

SVG-Viewer needed.

SVG-Viewer needed.

For the following routines, a nestable lock variable must be an integer variable of kind=omp_nest_lock_kind.

SVG-Viewer needed.

The nestable lock routines are as follows:

Restrictions Restrictions to OpenMP lock routines are as follows:

  3.9.1  omp_init_lock and omp_init_nest_lock
  3.9.2  omp_init_lock_with_hint and
omp_init_nest_lock_with_hint

  3.9.3  omp_destroy_lock and omp_destroy_nest_lock
  3.9.4  omp_set_lock and omp_set_nest_lock
  3.9.5  omp_unset_lock and omp_unset_nest_lock
  3.9.6  omp_test_lock and omp_test_nest_lock