![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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 OverviewDescription
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.
Types
Table 21 lists the types in package V_Semaphores.
Constants
Table 22 lists the types in package V_Semaphores.
Exceptions
Table 23 lists the exceptions in package V_Semaphores.
Package Specification
with ADA_Krn_Defs; package V_SEMAPHORES is pragma SUPPRESS(ALL_Checks); type binary_semaphore_id is private; type count_semaphore_id is private; subtype binary_count_t is integer range 0 .. 1; type semaphore_delete_option is
(DELETE_OPTION_FORCE,DELETE_OPTION_WARNING); Wait_Forever : constant duration := -1.0; DO_NOT_Wait : constant duration := 0.0; NO_Memory_FOR_SEMAPHORE : exception; SEMAPHORE_IN_USE : exception; SEMAPHORE_DELETED : exception; SEMAPHORE_NOT_AVAILABLE : exception; SEMAPHORE_TIMED_OUT : exception; UNEXPECTED_V_SEMAPHORE_ERROR : exception; Bind_Semaphore_NOT_SUPPORTED : exception; Bind_Semaphore_BAD_ARGUMENT : exception; NO_Memory_FOR_SEMAPHORE_NAME : exception; SEMAPHORE_NAME_ALREADY_BOUND : exception; Resolve_Semaphore_NOT_SUPPORTED : exception; Resolve_Semaphore_BAD_ARGUMENT : exception; Resolve_Semaphore_TIMED_OUT : exception; Resolve_Semaphore_FAILED : exception; NOT_A_SEMAPHORE_NAME : exception; type semaphore_result is (OBTAINED, TIMED_OUT, NOT_AVAILABLE,DELETED);
procedure Create_Semaphore (initial_count : in binary_count_t := 1; semaphore : out binary_semaphore_id; attr : in ADA_Krn_Defs.a_semaphore_attr_t := ADA_Krn_Defs.DEFAULT_SEMAPHORE_ATTR);
function Create_Semaphore (initial_count : in binary_count_t := 1; attr : in ADA_Krn_Defs.a_semaphore_attr_t := ADA_Krn_Defs.DEFAULT_SEMAPHORE_ATTR) return binary_semaphore_id;
procedure Create_Semaphore (initial_count : in integer := 1; semaphore : out count_semaphore_id; attr : in ADA_Krn_Defs.a_count_semaphore_attr_t := ADA_Krn_Defs.DEFAULT_COUNT_SEMAPHORE_ATTR);
function Create_Semaphore (initial_count : in integer := 1; attr : in ADA_Krn_Defs.a_count_semaphore_attr_t := ADA_Krn_Defs.DEFAULT_COUNT_SEMAPHORE_ATTR) return count_semaphore_id;
procedure Delete_Semaphore (semaphore : in binary_semaphore_id; delete_option : in semaphore_delete_option); procedure Delete_Semaphore (semaphore : in count_semaphore_id; delete_option : in semaphore_delete_option); procedure Signal_Semaphore (semaphore : in binary_semaphore_id); procedure Signal_Semaphore (semaphore : in count_semaphore_id);
procedure Wait_Semaphore (semaphore : in binary_semaphore_id; wait_time : in duration); procedure Wait_Semaphore (semaphore : in binary_semaphore_id; wait_time : in duration; result : out semaphore_result); procedure Wait_Semaphore (semaphore : in count_semaphore_id; wait_time : in duration); procedure Wait_Semaphore (semaphore : in count_semaphore_id; wait_time : in duration; result : out semaphore_result);
procedure Bind_Semaphore (name : in string; semaphore : in binary_semaphore_id);
procedure Bind_Semaphore (name : in string; semaphore : in count_semaphore_id);
procedure Resolve_Semaphore (name : in string; semaphore : out binary_semaphore_id; wait_time : in duration := Wait_Forever); function Resolve_Semaphore (name : in string; wait_time : in duration := Wait_Forever) return binary_semaphore_id; procedure Resolve_Semaphore (name : in string; semaphore : out count_semaphore_id; wait_time : in duration := Wait_Forever); function Resolve_Semaphore (name : in string; wait_time : in duration := Wait_Forever) return count_semaphore_id;
private type binary_semaphore_rec; type binary_semaphore_id is access binary_semaphore_rec; type count_semaphore_rec; type count_semaphore_id is access count_semaphore_rec; end V_SEMAPHORES;
Procedures and Functions in Package V_Semaphoresprocedure Bind_Semaphore
Syntax
procedure Bind_Semaphore (name : in string; semaphore : in binary_semaphore_id); procedure Bind_Semaphore (name : in string; semaphore : in count_semaphore_id);Arguments
- name
Semaphore's name. The name can be any sequence of characters. An exact match is done for all name searches. (My_Sema differs from my_sema.)
- semaphore
Description
Bind_Semaphore binds a name to a previously created semaphore.
Exceptions
- No_Memory_For_Semaphore_Name
Name could not be bound because of insufficient memory.
- Bind_Semaphore_Not_Supported
Name services are not supported by the underlying RTS.
- Bind_Semaphore_Bad_Argument
- Semaphore_Name_Already_Bound
Name was already bound to another object or procedure.
Warning: For self-hosts, names are only known within a single program. Name binding and resolution services are more applicable to the cross-target environment.
procedure/function Create_Semaphore
Syntax
procedure Create_Semaphore (initial_count : in binary_count_t := 1; semaphore : out binary_semaphore_id; attr : in ADA_Krn_Defs.a_semaphore_attr_t := ADA_Krn_Defs.DEFAULT_SEMAPHORE_ATTR);
function Create_Semaphore (initial_count : in binary_count_t := 1; attr : in ADA_Krn_Defs.a_semaphore_attr_t := ADA_Krn_Defs.DEFAULT_SEMAPHORE_ATTR) return binary_semaphore_id;
procedure Create_Semaphore (initial_count : in integer := 1; semaphore : out count_semaphore_id; attr : in ADA_Krn_Defs.a_count_semaphore_attr_t := ADA_Krn_Defs.DEFAULT_COUNT_SEMAPHORE_ATTR);
function Create_Semaphore (initial_count : in integer := 1; attr : in ADA_Krn_Defs.a_count_semaphore_attr_t := ADA_Krn_Defs.DEFAULT_COUNT_SEMAPHORE_ATTR) return count_semaphore_id;Arguments
- attr
For the binary Create_Semaphore, attr points to an Ada_Krn_Defs.Semaphore_Attr_T record. For the counting Create_Semaphore, attr points to an Ada_Krn_Defs.Count_Semaphore_Attr_T record. These records contain the binary/counting attributes. These are dependent on the underlying threaded runtime. The type definitions of Semaphore_Attr_T and Count_Semaphore_Attr_T and the different options supported are found in ada_krn_defs.a.
The attr parameter has been defaulted to Default_Semaphore_Attr or Default_Count_Semaphore_Attr. Unless you want to do something special, the default will suffice. VADS Micro defaults to FIFO queuing when a task blocks waiting for a semaphore.
For the VADS Micro counting Create_Semaphore, use Ada_Krn_Defs.Default_Count_Intr_Attr to protect the critical region for updating the semaphore count by disabling all interrupts.
Use the subprogram Ada_Krn_Defs.Count_Intr_Attr_Init to initialize the attributes so that a subset of the interrupts are disabled.
If the counting semaphore is to be signaled from an Isr, it must be protected by disabling interrupts.
- initial_count
Initial number of resources allocated to the semaphore. Binary semaphores are restricted to an initial count of 0 or 1. Binary semaphores with an initial value of 0 can be used for event posting.
- semaphore
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
procedure Delete_Semaphore (semaphore : in binary_semaphore_id; delete_option : in semaphore_delete_option); procedure Delete_Semaphore (semaphore : in count_semaphore_id; delete_option : in semaphore_delete_option);Arguments
- delete_option
Action to be taken if the semaphore is in use. Possible values are:
- Delete_Option_Force
Ready all waiting tasks. These tasks' calls to Wait_Semaphore raise the exception Semaphore_Deleted or return the result value Deleted. The semaphore is deleted.
- Delete_Option_Warning
Raise the exception Semaphore_In_Use in the calling task. The semaphore is not deleted.
- semaphore
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
- Semaphore_In_Use
An attempt is made to delete a semaphore when tasks are waiting on the semaphore and Delete_Option_Warning has been specified.
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
procedure Resolve_Semaphore (name : in string; semaphore : out binary_semaphore_id; wait_time : in duration := Wait_Forever); function Resolve_Semaphore (name : in string; wait_time : in duration := Wait_Forever) return binary_semaphore_id; procedure Resolve_Semaphore (name : in string; semaphore : out count_semaphore_id; wait_time : in duration := Wait_Forever); function Resolve_Semaphore (name : in string; wait_time : in duration := Wait_Forever) return count_semaphore_id;Arguments
- name
- semaphore
- wait_time
Amount of time the user is willing to wait for the name to be bound. Two allowable predefined values are:
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
- Not_A_Semaphore_Name
Raised by Resolve_Semaphore if the name is bound, but not to a semaphore object.
- Resolve_Semaphore_Bad_Argument
Raised if Resolve_Semaphore is called with a null name.
- Resolve_Semaphore_Failed
Raised by Resolve_Semaphore if a nonwaited attempt was made to resolve a name to a semaphore, 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 semaphore in the given time interval.
Warning: For self-hosts, names are only known within a single program. Name binding and resolution services are more applicable to the cross-target environment.
procedure Signal_Semaphore
Syntax
procedure Signal_Semaphore (semaphore : in binary_semaphore_id); procedure Signal_Semaphore (semaphore : in count_semaphore_id);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
procedure Wait_Semaphore (semaphore : in binary_semaphore_id; wait_time : in duration); procedure Wait_Semaphore (semaphore : in binary_semaphore_id; wait_time : in duration; result : out semaphore_result); procedure Wait_Semaphore (semaphore : in count_semaphore_id; wait_time : in duration); procedure Wait_Semaphore (semaphore : in count_semaphore_id; wait_time : in duration; result : out semaphore_result);Arguments
- result
- semaphore
- wait_time
Amount of time the user is willing to wait for the resource governed by the semaphore. Two allowable predefined values are:
Description
Do not call Wait_Semaphore from an interrupt service routine, unless the wait_time is specified as Do_Not_Wait.
Exceptions/Results
- Semaphore_Deleted/Deleted
Semaphore deleted while the task is waiting.
- Semaphore_Not_Available/Not_Available
A nonwaited attempt is made to obtain the semaphore and the semaphore is not available.
- Semaphore_Timed_Out/Timed_Out
A timed wait is attempted and the semaphore did not become available in the given time interval.
- Obtained
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. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |