TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Mutexes and Condition Variables (Package V_Mutexes)

This section contains an overview describing this package. This overview section is followed by a detailed description of each subprogram in this package.

The following topics are covered in this section:


Package Overview

Description

Package V_Mutexes provides mutexes and condition variables. It is layered directly on top of the V_I_Mutex package, which provides abort-safe mutexes and condition variables.

There are two varieties of mutexes: normal and recursive.

Normal mutexes can be used in conjunction with condition variables and provide the functionality described in Posix 1003.4a.

Recursive mutexes cannot be used in conjunction with condition variables; this is enforced by the typing system. Recursive mutexes are layered on top of normal mutexes, and support recursive locking by a given task. That is, when a task succeeds in locking a given mutex, it can recursively lock the mutex without blocking. Subsequent unlocks do not release the lock until the recursion depth has reached 0. Recursive mutexes detect and raise exceptions for invalid unlock and delete operations.

Mutexes (both normal and recursive) can be created with specific attributes. If the underlying kernel does not support the attribute, an exception is raised during creation.

Condition variables can also be created with specific queuing behavior. If the underlying kernel does not support the specified behavior, an exception is raised during creation.

Mutexes and condition variables can be shared between programs by using the bind and resolve name services.

Mutex operations are provided to create, delete, bind, resolve, lock, and unlock mutexes.

Priority-ceiling-specific mutex operations are provided to set and return the priority ceiling of a mutex.

Condition variable operations are provided to create, delete, bind, resolve, signal, broadcast, and wait.

Package Procedures and Functions

Table 12 lists the procedures and functions in package V_Mutexes with a brief description of each subprogram.

Table 12 Package Procedures and Functions
Name
Description
procedure Bind_Cond
Bind name to condition variable.
procedure Bind_Mutex
Bind name to mutex.
procedure Broadcast_Cond
Broadcast condition variable.
procedure/function Create_Cond
Create and initialize condition variable.
procedure/function Create_Mutex
Create and initialize mutex.
procedure Delete_Cond
Delete condition variable.
procedure Delete_Mutex
Delete mutex.
function Get_Priority_Ceiling_Mutex
Return mutex priority ceiling.
procedure Lock_Mutex
Attempt to lock mutex.
procedure/function Resolve_Cond
Resolve name into condition variable.
procedure/function Resolve_Mutex
Resolve name into mutex.
procedure Set_Priority_Ceiling_Mutex
Set mutex priority ceiling.
procedure Signal_Cond
Signal condition variable.
procedure Signal_Unlock_Cond
Signal condition variable/unlock mutex.
procedure/function Timed_Wait_Cond
Provide timed block of calling task.
function Trylock_Mutex
Attempt to lock mutex.
procedure Unlock_Mutex
Unlock mutex.
procedure Wait_Cond
Block task on condition variable.

Types

Table 13 lists the types used in package V_Mutexes

Table 13 Types
Type
Description
Mutex_Id
A private type used to identify a mutex.
R_Mutex_Id
A private type used to identify a recursive mutex.
Cond_Id
A private type used to identify a condition variable.
Cond_Result
Returned by the functional version of Timed_Wait_Cond to indicate the result of the operation.

Constants

Table 14 Constants
Name
Description
Wait_Forever
Used with the Resolve_Mutex or Resolve_Cond services to specify an indefinite wait for the name to be bound.
Do_Not_Wait
Used with the Resolve_Mutex or Resolve_Cond services to specify no wait at all for the name to be bound.
Table 14 lists the types used in package V_Mutexes

Mutex Exceptions

Table 15 lists the mutex exceptions used in package V_Mutexes

Table 15 Mutex Exceptions
Name
Description
No_Memory_For_Mutex
Raised by Create_Mutex if an attempt is made to create a mutex and there is insufficient memory for the mutex object in the system pool.
Mutex_Attr_Not_Supported
Raised by Create_Mutex if the underlying kernel does not support the specified attribute.
Mutex_Locked
Raised by Delete_Mutex if an attempt is made to delete a mutex and the mutex is locked. This is supported only for recursive mutexes.
Bind_Mutex_Not_Supported
Raised if name services are not supported by the underlying RTS.
Bind_Mutex_Bad_Argument
Raised if Bind_Mutex is called with a null name.
No_Memory_For_Mutex_Name
Raised if an attempt is made to bind a name to a mutex and there is insufficient memory.
Mutex_Name_Already_Bound
Raised if an attempt is made to bind a name to a mutex and the name is already bound to another object or procedure.
Resolve_Mutex_Not_Supported
Raised if name services are not supported by the underlying RTS.
Resolve_Mutex_Bad_Argument
Raised if Resolve_Mutex is called with a null name.
Resolve_Mutex_Timed_Out
Raised by Resolve_Mutex if a timed wait is attempted and the name is not bound to a mutex in the given time interval.
Resolve_Mutex_Failed
Raised by Resolve_Mutex if a non-waited attempt is made to resolve a name to a mutex, and the name is not already bound.
Not_A_Mutex_Name
Raised by Resolve_Mutex if the name is bound, but not to a mutex object.
Unexpected_V_Mutex_Error
Raised by a mutex operation if an unexpected error occurs during a V_Mutexes operation.

Condition Variable Exceptions

Table 16 lists the condition variable exceptions used in package V_Mutexes

Table 16 Condition Variable Exceptions
Name
Description
No_Memory_For_Cond
Raised by Create_Cond if an attempt is made to create a condition variable and there is insufficient memory for the condition variable object in the system pool.
lCond_Queuing_Not_Supported
Raised by Create_Cond if the underlying kernel does not support the specified queuing behavior.
Cond_Timed_Out
Raised by the procedural form of Timed_Wait_Cond if the specified duration is exceeded.
Bind_Cond_Not_Supported
Raised if name services are not supported by the underlying RTS.
Bind_Cond_Bad_Argument
Raised if Bind_Cond is called with a null name.
No_Memory_For_Cond_Name
Raised if an attempt is made to bind a name to a condition variable and there is insufficient memory.
Cond_Name_Already_Bound
Raised if an attempt is made to bind a name to a condition variable and the name has already been bound to another object or procedure.
Resolve_Cond_Not_Supported
Raised if name services are not supported by the underlying RTS.
Resolve_Cond_Bad_Argument
Raised if Resolve_Cond is called with a null name.
Resolve_Cond_Timed_Out
Raised by Resolve_Cond if a timed wait is attempted and the name is not bound to a condition variable in the given time interval.
Resolve_Cond_Failed
Raised by Resolve_Cond if a nonwaited attempt is made to resolve a name to a condition variable, and the name is not already bound.
Not_A_Cond_Name
Raised by Resolve_Cond if the name is bound, but not to a condition variable object.
Unexpected_V_Cond_Error
Raised by a condition variable operation if the condition variable parameter is not a valid condition variable.

Package Specification


Procedures and Functions in Package V_Mutexes

procedure Bind_Cond

Syntax

Arguments

Description

Bind_Cond binds a name to a previously created condition variable.

Exceptions

procedure Bind_Mutex

Syntax

Arguments

Description

Bind_Mutex binds a name to a previously created mutex.

Exceptions

procedure Broadcast_Cond

Syntax

Arguments

Description

procedure Broadcast_Cond broadcasts a condition variable, "waking up" all tasks that are waiting on the condition variable. However, no awakened task resumes execution until the associated mutex is unlocked.

procedure/function Create_Cond

Syntax

Arguments

Description

Subprogram Create_Cond creates and initializes a condition variable. Two versions are supplied: a procedure that returns Cond_Id as an out parameter, and a function that returns Cond_Id as the result.

The created condition variable can be shared with other programs by using the Bind_Cond/Resolve_Cond services.

For a description of condition variable queuing behaviors, see v_i_cifo.a.

Here are some examples of usage:

Exceptions

procedure/function Create_Mutex

Syntax

Arguments

Description

Create_Mutex creates and initializes a mutex. Two versions are supplied: a procedure that returns Mutex_Id as an out parameter, and a function returning Mutex_Id as the result.

The created mutex can be shared with other programs by using the Bind_Mutex/Resolve_Mutex services.

For a description of mutex attributes, see ada_krn_defs.a in the standard directory.

Here are some examples of usage:

Exceptions

procedure Delete_Cond

Syntax

Arguments

Description

procedure Delete_Cond deletes a previously created condition variable.

If a condition variable is shared between programs by using the Bind_Cond/Resolve_Cond services, it must be deleted only in the program where it was created.

procedure Delete_Mutex

Syntax

Arguments

Description

procedure Delete_Mutex deletes a previously created mutex.

If a mutex is shared between programs by using the Bind_Mutex/Resolve_Mutex services, it must be deleted only in the program where it was created.

Exceptions

function Get_Priority_Ceiling_Mutex

Syntax

Arguments

Description

function Get_Priority_Ceiling_Mutex returns the ceiling priority of the given mutex.

Exceptions

procedure Lock_Mutex

Syntax

Arguments

Description

procedure Lock_Mutex attempts to lock the mutex.

For non-recursive mutexes, if the mutex is currently locked, the task is blocked until the mutex is no longer locked and there are no other tasks waiting "ahead" associated with the mutex. Attempting to lock a mutex that is already locked by the calling task results in an infinite wait for the calling task.

For recursive mutexes, if the mutex is currently locked by the calling task, the depth is incremented and no blocking occurs. If the mutex is locked by another task, the task is blocked until the mutex is no longer locked and there are no other tasks waiting ahead of it.

procedure/function Resolve_Cond

Syntax

Arguments

Description

Subprogram Resolve_Cond resolves a name into a condition variable that is created and bound in another program. Two versions are supplied: a procedure that returns Cond_Id as an out parameter, and a function that returns Cond_Id as the result.

subprogram Resolve_Cond first attempts to find an already bound name that exactly matches the name parameter. For a match, it returns immediately. Otherwise, it returns according to the wait_time parameter.

Exceptions

procedure/function Resolve_Mutex

Syntax

Arguments

Description

Subprogram Resolve_Mutex resolves a name into a mutex that is created and bound in another program. Two versions are supplied: a procedure that returns Mutex_Id as an out parameter, and a function that returns Mutex_Id as the result.

Subprogram Resolve_Mutex first attempts to find an already bound name that exactly matches the name parameter. For a match, it returns immediately. Otherwise, it returns according to the wait_time parameter.

Exceptions

procedure Set_Priority_Ceiling_Mutex

Syntax

Arguments

Description

procedure Set_Priority_Ceiling sets the given mutex priority ceiling.

Exceptions

procedure Signal_Cond

Syntax

Arguments

Description

procedure Signal_Cond signals a condition variable, "waking up" the next (as defined by the queuing behavior) task that is waiting on the condition variable. However, the awakened task does not resume execution until the associated mutex is unlocked.

procedure Signal_Unlock_Cond

Syntax

Arguments

Description

procedure SIgnal_Unlock_Cond signals a condition variable and unlocks the specified mutex. This is more efficient than separate calls to Signal_Cond and Unlock_Mutex.

procedure/function Timed_Wait_Cond

Syntax

Arguments

Description

Subprogram Timed_Wait_Cond blocks the calling task on the condition variable until either a corresponding signal/broadcast is performed on the condition variable, or the time duration has expired (assuming the duration is positive). If the duration is zero, it returns immediately, without blocking. If the duration is negative, it does not time out; that is, it waits indefinitely. There are two versions: the procedure raises an exception on timeout (otherwise, it returns normally), and the function returns the result of the wait. If successful, the calling task holds the lock on the mutex upon return.

Exceptions

function Trylock_Mutex

Syntax

Arguments

Description

Function Trylock_Mutex attempts to lock the mutex. If the mutex is already locked, it returns False. Otherwise, it locks the mutex (as specified by the Lock_Mutex routine) and returns True. No blocking ever occurs as a result of this call.

procedure Unlock_Mutex

Syntax

Arguments

Description

Procedure Unlock_Mutex unlocks the mutex, enabling the next task waiting to lock the mutex to proceed. If the mutex is a recursive mutex, however, the depth is first decremented. If the subsequent depth is greater than zero, the calling task retains the lock. If the depth is zero, then the lock is given up.

Exceptions

procedure Wait_Cond

Syntax

Arguments

Description

Procedure Wait_Cond blocks the calling task until a corresponding signal/broadcast is performed on the condition variable, and the mutex is unlocked. It is possible, however, that a task may return from Wait_Cond "early", because of an abort and/or other operating-system events (see V_I_Mutex). It is therefore essential that calls to Wait_Cond be wrapped inside a loop that tests for the associated predicate before proceeding. Upon return from Wait_Cond, the mutex is locked by the calling task.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2003, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS