TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Semaphores (Package V_Semaphores)

This chapter 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

The package V_Semaphores provides operations for binary and counting semaphores. The semaphore data structure is allocated by using the Ada new allocator.

V_Semaphores has been layered on the Ada Kernel binary and counting semaphore objects.

Begin Tornado Only

VADSexec semaphores are implemented using Tornado binary and counting semaphores. The Interrupt_Flag and Interrupt_Status creation parameters are recognized but have no effect.

The restrictions on the use of Tornado semaphores apply to VADSexec semaphores. In particular, semaphores can be given from interrupt level, but should not be taken by an interrupt handler.

End Tornado Only

The following operations are overloaded and apply to both binary and counting semaphores.

The operation Create_Semaphore creates a semaphore with an initial semaphore count. The semaphore count indicates the number of available resources; for example, an initial value of 1 allows only one task at a time to access the semaphore.

Wait_Semaphore decrements the semaphore count, causing the task to block on the semaphore if the semaphore is not available (the count becomes negative). The queuing order for blocked tasks depends on the attributes passed to Create_Semaphore. VADS Micro only supports first-in/first-out (FIFO) queuing for binary semaphores. For counting semaphores, FIFO or priority ordered queues are supported with FIFO as the default. The task must specify how long it is willing to wait for the semaphore.

Wait_Semaphore enables you to select the error notification method. If a result parameter is provided in the call, a result status is returned in the parameter; otherwise, an exception is raised if an error occurs.

Signal_Semaphore increments the semaphore count, awakening any task that is waiting on the semaphore. If the awakened task is of sufficient priority, it preempts the current task.

Delete_Semaphore removes a semaphore. The user must specify the action to be taken if tasks are currently waiting on the semaphore.

Bind_Semaphore and Resolve_Semaphore allow a semaphore to be shared between programs. Bind_Semaphore binds a name to a semaphore previously created in the current program. Resolve_Semaphore resolves a name into a semaphore that was created and bound in another program.

If a task is aborted while accessing a semaphore, the resource is permanently locked.

Package Procedures and Functions

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

Table 20 Procedures and Functions
Name
Description
procedure Bind_Semaphore
Bind a name to a semaphore.
procedure/function Create_Semaphore
Create and initialize a semaphore.
procedure Delete_Semaphore
Delete a semaphore.
procedure/function Resolve_Semaphore
Resolve a name into a semaphore.
procedure Signal_Semaphore
Perform a signal operation on a semaphore.
procedure Wait_Semaphore
Perform a wait operation on a semaphore.

Types

Table 21 lists the types in package V_Semaphores.

Table 21 Types
Name
Description
Binary_Count_T
Restricts the range for the initial count of a binary semaphore.
Count_Semaphore_ID
A private type used to identify a counting semaphore.
Binary_Semaphore_ID
A private type used to identify a binary semaphore.
Semaphore_Delete_Option
Specifies the action to take during a call to Delete_Semaphore if tasks are waiting on the semaphore that is to be deleted. Possible values are:

Delete_Option_Force
Delete_Option_Warning

Semaphore_Result
Returns the completion status of the version of Wait_Semaphore that returns a status. Possible values are:

Obtained
Timed_Out
Not_Available
Deleted

Use pragma No_Image to eliminate the excess space overhead for enumeration types. The image array associated with an enumeration type is allocated in its own CONST subsection and is deleted by selective linking, if there are no uses of Enum_Type'image.

Constants

Table 22 lists the types in package V_Semaphores.

Table 22 Constants
Name
Description
Wait_Forever
Passed to the Wait_Time parameter of Wait_Semaphore to specify the semaphore should be waited on until it is signaled Additionally, this constant can be used with Resolve_Semaphore to specify waiting indefinitely or not at all for the name to be bound.
Do_Not_Wait
Passed to the Wait_Time parameter of Wait_Semaphore to specify that the call should not block on the semaphore. If the semaphore is not available, an appropriate status is returned or an exception is raised. Additionally, this constant can be used with Resolve_Semaphore to specify waiting indefinitely or not at all for the name to be bound.

Exceptions

Table 23 lists the exceptions in package V_Semaphores.

Table 23 Exceptions
Name
Description
Bind_Semaphore_Bad_Argument
Raised if Bind_Semaphore is called with a null name.
Bind_Semaphore_Not_Supported
Raised if name services are not supported by the underlying RTS.
No_Memory_For_Semaphore
Raised by Create_Semaphore if an attempt is made to create a semaphore and there is insufficient memory for the semaphore object.
No_Memory_For_Semaphore_Name
Raised if an attempt is made to bind a name to a mailbox and there is insufficient memory.
Not_A_Semaphore_Name
Raised by Resolve_Semaphore if the name is bound, but not to a mailbox object.
Resolve_Semaphore_Bad_Argument
Raised if Resolve_Semaphore is called with a null name.
Resolve_Semaphore_Failed
Raised by Resolve_Semaphore if a non-waited attempt was made to resolve a name to a mailbox, and the name wasn't already bound.
Resolve_Semaphore_Not_Supported
Raised if name services are not supported by the underlying RTS.
Resolve_Semaphore_Timed_Out
Raised by Resolve_Semaphore if a timed wait was attempted and the name wasn't bound to a mailbox in the given time interval.
Semaphore_Deleted
Raised by Wait_Semaphore if the semaphore is deleted while the task is waiting.
Semaphore_In_Use
Raised by Delete_Semaphore if an attempt is made to delete a semaphore when tasks are waiting on the semaphore and Delete_Option_Warning has been specified.
Semaphore_Name_Already_Bound
Raised if an attempt is made to bind a name to a mailbox and the name has already been bound to another object or procedure.
Semaphore_Not_Available
Raised by Wait_Semaphore if a non-waited attempt is made to obtain the semaphore and the semaphore is not available.
Semaphore_Timed_Out
Raised by Wait_Semaphore if a timed wait is attempted and the semaphore did not become available in the given time interval.
Unexpected_V_Semaphore_Error
Raised if a semaphore routine is called with an invalid pointer to a semaphore or called using a deleted semaphore.

Package Specification


Procedures and Functions in Package V_Semaphores

procedure Bind_Semaphore

Syntax

Arguments

Description

Bind_Semaphore binds a name to a previously created semaphore.

Exceptions

procedure/function Create_Semaphore

Syntax

Arguments

Description

Create_Semaphore creates and initializes a binary or counting semaphore. Two versions are supplied for each semaphore type: a procedure that returns the semaphore ID as an out parameter or a function that returns the semaphore ID.

The created semaphore can be shared with other programs by using the Bind_Semaphore/Resolve_Semaphore services.

Exceptions

Threaded Runtime

Create_Semaphore is layered upon Ada_Krn_I.Semaphore_Init or Ada_Krn_I.Count_Semaphore_Init. See them for more details about semaphore and counting semaphore attributes.

procedure Delete_Semaphore

Syntax

Arguments

Description

Delete_Semaphore is used to delete either a binary or a counting semaphore. Note that the memory allocated for the semaphore is always freed after the semaphore is deleted.

If a semaphore is shared between programs by using the Bind_Semaphore/Resolve_Semaphore services, it must be deleted only in the program where it was created.

Exceptions

Threaded Runtime

Delete_Semaphore is layered upon Ada_Krn_I.Semaphore_Destroy or Ada_Krn_I.Count_Semaphore_Destroy.

Note: For LynxOS there is no way to detect if a task is waiting on the semaphore, therefore Semaphore_In_Use will never be raised. Care must be taken to ensure that no task is waiting on the semaphore.

procedure/function Resolve_Semaphore

Syntax

Arguments

Description

Resolve_Semaphore resolves a name into a semaphore that was created and bound in another program. Two versions are supplied: a procedure that returns semaphore ID as an out parameter or a function returning the semaphore ID. Resolve_Semaphore 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 Signal_Semaphore

Syntax

Arguments

Description

Signal_Semaphore performs a signal operation on a semaphore. If tasks are waiting on the semaphore, the signal operation causes a waiting task to be readied. If the readied task has a higher priority than the current task, the waiting task preempts the current task.

This service can be called from an interrupt service routine. However, for a counting semaphore, the interrupt protected form must be used.

Threaded Runtime

Signal_Semaphore is layered upon Ada_Krn_I.Semaphore_Signal or Ada_Krn_I.Count_Semaphore_Signal.

procedure Wait_Semaphore

Syntax

Arguments

Description

Do not call Wait_Semaphore from an interrupt service routine, unless the wait_time is specified as Do_Not_Wait.

Exceptions/Results

Threaded Runtime

Wait_Semaphore is layered upon Ada_Krn_I.Semaphore_Wait or Ada_Krn_I.Count_Semaphore_Wait.


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