|
DataMuseum.dkPresents historical artifacts from the history of: Rational R1000/400 Tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about Rational R1000/400 Tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - downloadIndex: ┃ T V ┃
Length: 12615 (0x3147)
Types: TextFile
Names: »V«
└─⟦516dceb10⟧ Bits:30000751 8mm tape, Rational 1000, RCI_VADS
└─ ⟦9a14c9417⟧ »DATA«
└─⟦this⟧
with V_Interrupts;
package V_Semaphores is
pragma Suppress (All_Checks);
-- PURPOSE : V_SEMAPHORES provides binary or counting semaphores.
--
-- The following operations are overloaded and applicable to
-- either binary or counting semaphores.
--
-- The operation CREATE_SEMAPHORE creates a semaphore
-- with an initial semaphore count. The semaphore count
-- indicates the number of available resources; i.e., an
-- initial value of one would allow only one task at a
-- time to access the semaphore.
--
-- For binary semaphores, the initial semaphore count is restricted
-- to 0 or 1. A count of 1 indicates the resource is initially
-- available.
--
-- WAIT_SEMAPHORE decrements the semaphore's count, causing
-- the task to block on the semaphore if the semaphore is not
-- available (the count becomes negative). Blocked tasks
-- are queued on the semaphore in priority order, where
-- priorities have been specified via pragma PRIORITY.
-- Within priority levels, tasks are queued on a first-in-
-- first-out basis. The task must specify how long it is
-- willing to wait for the semaphore.
--
-- WAIT_SEMAPHORE has been declared as an overloaded procedure
-- to allow the user to select the method of error notification.
-- If a result parameter is provided in the call, a result status
-- will be returned in the parameter; otherwise, an exception
-- will be raised if an error occurs.
--
-- SIGNAL_SEMAPHORE will increment the semaphore's count,
-- awakening a task waiting on the semaphore, if any are
-- waiting.
--
-- DELETE_SEMAPHORE deletes a semaphore. The user must
-- specify the action to be taken if there are currently
-- tasks waiting on the semaphore.
--
-- NOTES : A task awakened by a signal to a semaphore may pre-empt
-- the currently executing task if the awakened task is of
-- sufficient priority.
-- The following type is used to identify a binary semaphore.
type Binary_Semaphore_Id is private;
-- The following type is used to identify a counting semaphore.
type Count_Semaphore_Id is private;
-- The following type restricts the range for the initial count of a
-- binary semaphore
subtype Binary_Count_T is Integer range 0 .. 1;
-- Objects of the following type are used to specify the action to take
-- during a call to DELETE_SEMAPHORE if tasks are waiting on the semaphore
-- that is to be deleted.
type Semaphore_Delete_Option is
(Delete_Option_Force, Delete_Option_Warning);
-- Where:
--
-- DELETE_OPTION_FORCE delete the semaphore even though
-- there may be tasks waiting at the
-- semaphore.
--
-- DELETE_OPTION_WARNING indicates that the semaphore should
-- only be deleted if there are no
-- waiting tasks.
-- The following constants may be used with WAIT_SEMAPHORE to specify
-- that the semaphore should either be waited on indefinitely or not
-- at all, respectively.
Wait_Forever : constant Duration := -1.0;
Do_Not_Wait : constant Duration := 0.0;
-- The following exceptions may be raised by the semaphore services:
No_Memory_For_Semaphore : exception;
-- NO_MEMORY_FOR_SEMAPHORE is raised if an attempt is made to
-- create a semaphore and there is not sufficient memory for
-- the semaphore object in the system pool.
Semaphore_In_Use : exception;
-- SEMAPHORE_IN_USE is raised if an attempt is made to delete
-- a semaphore when tasks are waiting on the semaphore and
-- delete_option_warning has been specified.
Semaphore_Deleted : exception;
-- SEMAPHORE_DELETED is raised by WAIT_SEMAPHORE if the semaphore
-- was deleted while the task was waiting.
Semaphore_Not_Available : exception;
-- SEMAPHORE_NOT_AVAILABLE is raised by WAIT_SEMAPHORE if a non-waited
-- attempt was made to obtain the semaphore, and the semaphore was
-- not available.
Semaphore_Timed_Out : exception;
-- SEMAPHORE_TIMED_OUT is raised by WAIT_SEMAPHORE if a timed wait
-- was attempted and the semaphore did not become available in the
-- given time interval.
Unexpected_V_Semaphore_Error : exception;
-- UNEXPECTED_V_SEMAPHORE_ERROR may be raised if an unexpected
-- error occurs during an V_SEMAPHORES operation.
-- The following type declares the result codes which may be returned
-- by the non-exception-raising version of the WAIT_SEMAPHORE
-- routine.
type Semaphore_Result is (Obtained, Timed_Out, Not_Available, Deleted);
-- WAIT_SEMAPHORE returns OBTAINED if the semaphore was obtained,
-- TIMED_OUT if a timed wait was performed and the semaphore was
-- not obtained in the specified interval, NOT_AVAILABLE if a
-- non-waited access was attempted and the semaphore was not
-- available, or DELETED if the semaphore was deleted while
-- the current task was waiting for it.
procedure Create_Semaphore (Initial_Count : in Binary_Count_T := 1;
Semaphore : out Binary_Semaphore_Id);
function Create_Semaphore (Initial_Count : in Binary_Count_T := 1)
return Binary_Semaphore_Id;
procedure Create_Semaphore
(Initial_Count : in Integer := 1;
Semaphore : out Count_Semaphore_Id;
Interrupt_Flag : in Boolean := False;
Interrupt_Status : in V_Interrupts.Interrupt_Status_T :=
V_Interrupts.Disable_Interrupt);
function Create_Semaphore
(Initial_Count : in Integer := 1;
Interrupt_Flag : in Boolean := False;
Interrupt_Status : in V_Interrupts.Interrupt_Status_T :=
V_Interrupts.Disable_Interrupt) return Count_Semaphore_Id;
-- Purpose: CREATE_SEMAPHORE creates and initializes a binary
-- or counting semaphore. Two versions are supplied for
-- each semaphore type, a procedure
-- that returns semaphore id as an out parameter or a function
-- returning the semaphore id.
--
-- Where:
--
-- initial_count indicates the initial value of the semaphore
-- counter (initial number of resources allocated
-- to the semaphore). A binary semaphore is restricted
-- to an initial value of 0 or 1.
--
-- semaphore identifies the semaphore created.
--
-- interrupt_flag normally, the critical region for updating the
-- semaphore's count is protected by a binary
-- semaphore. However, if INTERRUPT_FLAG is TRUE,
-- then its critical region is protected by disabling
-- interrupts using the INTERRUPT_STATUS parameter.
-- INTERRUPT_FLAG must be set to TRUE if the
-- counting semaphore is accessed from an ISR.
-- Defaults to FALSE. Not applicable to binary
-- semaphores.
--
-- interrupt_status if above INTERRUPT_FLAG is TRUE, then this value
-- is used to disable interrupts. Defaults to
-- disabling all interrupt levels. Not applicable
-- to binary semaphores.
--
-- Exceptions:
--
-- NO_MEMORY_FOR_SEMAPHORE is raised if the semaphore could not
-- be created due to insufficient memory.
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);
-- Purpose: DELETE_SEMAPHORE deletes a semaphore.
--
-- Where:
--
-- semaphore identifies the semaphore to be deleted.
--
-- delete_option specifies the action to be taken if the
-- semaphore is in use:
--
-- when delete_option_force =>
--
-- Ready all waiting tasks. These tasks' calls
-- to WAIT_SEMAPHORE will raise the exception
-- SEMAPHORE_DELETED, or return the result value
-- DELETED.
--
-- The semaphore is deleted.
--
-- when delete_option_warning =>
--
-- Raise the exception SEMAPHORE_IN_USE in the
-- calling task.
--
-- The semaphore is not deleted.
--
-- Exceptions:
--
-- SEMAPHORE_IN_USE is raised if delete_option_warning was
-- specified and tasks were waiting on the semaphore.
procedure Signal_Semaphore (Semaphore : in Binary_Semaphore_Id);
procedure Signal_Semaphore (Semaphore : in Count_Semaphore_Id);
-- Purpose: SIGNAL_SEMAPHORE performs a signal operation on
-- a semaphore.
--
-- Where:
--
-- semaphore identifies the semaphore to be signaled.
--
-- Notes: If there are any tasks waiting on the semaphore, the
-- signal operation will cause the waiting task to be
-- readied. If the readied task has a priority higher
-- than the currently running task, then the waiting
-- task will pre-empt the currently running task.
--
-- This service may be called from an interrupt
-- service routine.
--
-- Exceptions:
--
-- None.
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);
-- Purpose: WAIT_SEMAPHORE performs a wait operation on a
-- semaphore.
--
-- WAIT_SEMAPHORE should not be called from an
-- interrupt service routine.
--
-- Where:
--
-- semaphore identifies the semaphore on which to wait.
--
-- wait_time specifies the amount of time the user is
-- willing to wait for the resource governed by
-- the semaphore. Wait_time options are:
--
-- if wait_time = WAIT_FOREVER then
-- willing to wait forever
-- elsif wait_time = DO_NOT_WAIT
-- do not wait if semaphore is not available
-- else
-- wait wait_time seconds for
-- the semaphore to become available.
-- end if
--
-- Exceptions/Results:
--
-- SEMAPHORE_DELETED is raised (or result value DELETED is returned)
-- if the semaphore was deleted while the task was waiting.
--
-- SEMAPHORE_NOT_AVAILABLE is raised (or result value NOT_AVAILABLE
-- is returned) if DO_NOT_WAIT was specified and the semaphore was
-- not available.
--
-- SEMAPHORE_TIMED_OUT is raised (or result value TIMED_OUT is returned)
-- if the semaphore could not be obtained within the specified time
-- interval.
--
-- The result value OBTAINED is returned if the semaphore is obtained.
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;