Lock Routines

| OPENMP API Specification: "Version 5.2 -- GIT rev 95b2e3a44"

18.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 eﬀect of the hint is implementation deﬁned. An OpenMP implementation can use this hint to select a usage-speciﬁc 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 unspeciﬁed.

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 diﬀerent 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 eﬀects 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

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.

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

The simple lock routines are as follows:

The omp_init_lock routine initializes a simple lock;
The omp_init_lock_with_hint routine initializes a simple lock and attaches a hint to it;
The omp_destroy_lock routine uninitializes a simple lock;
The omp_set_lock routine waits until a simple lock is available and then sets it;
The omp_unset_lock routine unsets a simple lock; and
The omp_test_lock routine tests a simple lock and sets it if it is available.

Nestable Lock Routines

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.

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

The nestable lock routines are as follows:

The omp_init_nest_lock routine initializes a nestable lock;
The omp_init_nest_lock_with_hint routine initializes a nestable lock and attaches a hint to it;
The omp_destroy_nest_lock routine uninitializes a nestable lock;
The omp_set_nest_lock routine waits until a nestable lock is available and then sets it;
The omp_unset_nest_lock routine unsets a nestable lock; and
The omp_test_nest_lock routine tests a nestable lock and sets it if it is available.

Restrictions

Restrictions to OpenMP lock routines are as follows:

The use of the same OpenMP lock in diﬀerent contention groups results in unspeciﬁed behavior.

18.10.2 omp_get_wtick

[next] [prev] [prev-tail] [front] [up]