242 lines
10 KiB
Ada
242 lines
10 KiB
Ada
------------------------------------------------------------------------------
|
|
-- --
|
|
-- GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS --
|
|
-- --
|
|
-- S Y S T E M . T A S K I N G . P R O T E C T E D _ O B J E C T S --
|
|
-- --
|
|
-- S p e c --
|
|
-- --
|
|
-- Copyright (C) 1992-2020, Free Software Foundation, Inc. --
|
|
-- --
|
|
-- GNARL is free software; you can redistribute it and/or modify it under --
|
|
-- terms of the GNU General Public License as published by the Free Soft- --
|
|
-- ware Foundation; either version 3, or (at your option) any later ver- --
|
|
-- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
|
|
-- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
|
|
-- or FITNESS FOR A PARTICULAR PURPOSE. --
|
|
-- --
|
|
-- As a special exception under Section 7 of GPL version 3, you are granted --
|
|
-- additional permissions described in the GCC Runtime Library Exception, --
|
|
-- version 3.1, as published by the Free Software Foundation. --
|
|
-- --
|
|
-- You should have received a copy of the GNU General Public License and --
|
|
-- a copy of the GCC Runtime Library Exception along with this program; --
|
|
-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
|
|
-- <http://www.gnu.org/licenses/>. --
|
|
-- --
|
|
-- GNARL was developed by the GNARL team at Florida State University. --
|
|
-- Extensive contributions were provided by Ada Core Technologies, Inc. --
|
|
-- --
|
|
------------------------------------------------------------------------------
|
|
|
|
-- This package provides necessary definitions to handle simple (i.e without
|
|
-- entries) protected objects.
|
|
|
|
-- All the routines that handle protected objects with entries have been moved
|
|
-- to two children: Entries and Operations. Note that Entries only contains
|
|
-- the type declaration and the OO primitives. This is needed to avoid
|
|
-- circular dependency.
|
|
|
|
-- This package is part of the high level tasking interface used by the
|
|
-- compiler to expand Ada 95 tasking constructs into simpler run time calls
|
|
-- (aka GNARLI, GNU Ada Run-time Library Interface)
|
|
|
|
-- Note: the compiler generates direct calls to this interface, via Rtsfind.
|
|
-- Any changes to this interface may require corresponding compiler changes
|
|
-- in exp_ch9.adb and possibly exp_ch7.adb and exp_attr.adb
|
|
|
|
package System.Tasking.Protected_Objects is
|
|
pragma Elaborate_Body;
|
|
|
|
---------------------------------
|
|
-- Compiler Interface (GNARLI) --
|
|
---------------------------------
|
|
|
|
-- The compiler will expand in the GNAT tree the following construct:
|
|
|
|
-- protected PO is
|
|
-- procedure P;
|
|
-- private
|
|
-- open : boolean := false;
|
|
-- end PO;
|
|
|
|
-- protected body PO is
|
|
-- procedure P is
|
|
-- ...variable declarations...
|
|
-- begin
|
|
-- ...B...
|
|
-- end P;
|
|
-- end PO;
|
|
|
|
-- as follows:
|
|
|
|
-- protected type poT is
|
|
-- procedure p;
|
|
-- private
|
|
-- open : boolean := false;
|
|
-- end poT;
|
|
-- type poTV is limited record
|
|
-- open : boolean := false;
|
|
-- _object : aliased protection;
|
|
-- end record;
|
|
-- procedure poPT__pN (_object : in out poTV);
|
|
-- procedure poPT__pP (_object : in out poTV);
|
|
-- freeze poTV [
|
|
-- procedure poTVI (_init : in out poTV) is
|
|
-- begin
|
|
-- _init.open := false;
|
|
-- object-init-proc (_init._object);
|
|
-- initialize_protection (_init._object'unchecked_access,
|
|
-- unspecified_priority);
|
|
-- return;
|
|
-- end _init_proc;
|
|
-- ]
|
|
-- po : poT;
|
|
-- poTVI (poTV!(po));
|
|
|
|
-- procedure poPT__pN (_object : in out poTV) is
|
|
-- poR : protection renames _object._object;
|
|
-- openP : boolean renames _object.open;
|
|
-- ...variable declarations...
|
|
-- begin
|
|
-- ...B...
|
|
-- return;
|
|
-- end poPT__pN;
|
|
|
|
-- procedure poPT__pP (_object : in out poTV) is
|
|
-- procedure _clean is
|
|
-- begin
|
|
-- unlock (_object._object'unchecked_access);
|
|
-- return;
|
|
-- end _clean;
|
|
-- begin
|
|
-- lock (_object._object'unchecked_access);
|
|
-- B2b : begin
|
|
-- poPT__pN (_object);
|
|
-- at end
|
|
-- _clean;
|
|
-- end B2b;
|
|
-- return;
|
|
-- end poPT__pP;
|
|
|
|
Null_Protected_Entry : constant := Null_Entry;
|
|
|
|
Max_Protected_Entry : constant := Max_Entry;
|
|
|
|
type Protected_Entry_Index is new Entry_Index
|
|
range Null_Protected_Entry .. Max_Protected_Entry;
|
|
|
|
type Barrier_Function_Pointer is access
|
|
function
|
|
(O : System.Address;
|
|
E : Protected_Entry_Index)
|
|
return Boolean;
|
|
-- Pointer to a function which evaluates the barrier of a protected
|
|
-- entry body. O is a pointer to the compiler-generated record
|
|
-- representing the protected object, and E is the index of the
|
|
-- entry serviced by the body.
|
|
|
|
type Entry_Action_Pointer is access
|
|
procedure
|
|
(O : System.Address;
|
|
P : System.Address;
|
|
E : Protected_Entry_Index);
|
|
-- Pointer to a procedure which executes the sequence of statements
|
|
-- of a protected entry body. O is a pointer to the compiler-generated
|
|
-- record representing the protected object, P is a pointer to the
|
|
-- record of entry parameters, and E is the index of the
|
|
-- entry serviced by the body.
|
|
|
|
type Entry_Body is record
|
|
Barrier : Barrier_Function_Pointer;
|
|
Action : Entry_Action_Pointer;
|
|
end record;
|
|
-- The compiler-generated code passes objects of this type to the GNARL
|
|
-- to allow it to access the executable code of an entry body and its
|
|
-- barrier.
|
|
|
|
type Protection is limited private;
|
|
-- This type contains the GNARL state of a protected object. The
|
|
-- application-defined portion of the state (i.e. private objects)
|
|
-- is maintained by the compiler-generated code.
|
|
-- Note that there are now 2 Protection types. One for the simple
|
|
-- case (no entries) and one for the general case that needs the whole
|
|
-- Finalization mechanism.
|
|
-- This split helps in the case of restricted run time where we want to
|
|
-- minimize the size of the code.
|
|
|
|
type Protection_Access is access all Protection;
|
|
|
|
Null_PO : constant Protection_Access := null;
|
|
|
|
function Get_Ceiling
|
|
(Object : Protection_Access) return System.Any_Priority;
|
|
-- Returns the new ceiling priority of the protected object
|
|
|
|
procedure Initialize_Protection
|
|
(Object : Protection_Access;
|
|
Ceiling_Priority : Integer);
|
|
-- Initialize the Object parameter so that it can be used by the runtime
|
|
-- to keep track of the runtime state of a protected object.
|
|
|
|
procedure Lock (Object : Protection_Access);
|
|
-- Lock a protected object for write access. Upon return, the caller
|
|
-- owns the lock to this object, and no other call to Lock or
|
|
-- Lock_Read_Only with the same argument will return until the
|
|
-- corresponding call to Unlock has been made by the caller.
|
|
|
|
procedure Lock_Read_Only (Object : Protection_Access);
|
|
-- Lock a protected object for read access. Upon return, the caller
|
|
-- owns the lock for read access, and no other calls to Lock with the
|
|
-- same argument will return until the corresponding call to Unlock
|
|
-- has been made by the caller. Other calls to Lock_Read_Only may (but
|
|
-- need not) return before the call to Unlock, and the corresponding
|
|
-- callers will also own the lock for read access.
|
|
|
|
procedure Set_Ceiling
|
|
(Object : Protection_Access;
|
|
Prio : System.Any_Priority);
|
|
-- Sets the new ceiling priority of the protected object
|
|
|
|
procedure Unlock (Object : Protection_Access);
|
|
-- Relinquish ownership of the lock for the object represented by
|
|
-- the Object parameter. If this ownership was for write access, or
|
|
-- if it was for read access where there are no other read access
|
|
-- locks outstanding, one (or more, in the case of Lock_Read_Only)
|
|
-- of the tasks waiting on this lock (if any) will be given the
|
|
-- lock and allowed to return from the Lock or Lock_Read_Only call.
|
|
|
|
private
|
|
type Protection is record
|
|
L : aliased Task_Primitives.Lock;
|
|
-- Lock used to ensure mutual exclusive access to the protected object
|
|
|
|
Ceiling : System.Any_Priority;
|
|
-- Ceiling priority associated to the protected object
|
|
|
|
New_Ceiling : System.Any_Priority;
|
|
-- New ceiling priority associated to the protected object. In case
|
|
-- of assignment of a new ceiling priority to the protected object the
|
|
-- frontend generates a call to set_ceiling to save the new value in
|
|
-- this field. After such assignment this value can be read by means
|
|
-- of the 'Priority attribute, which generates a call to get_ceiling.
|
|
-- However, the ceiling of the protected object will not be changed
|
|
-- until completion of the protected action in which the assignment
|
|
-- has been executed (AARM D.5.2 (10/2)).
|
|
|
|
Owner : Task_Id;
|
|
-- This field contains the protected object's owner. Null_Task
|
|
-- indicates that the protected object is not currently being used.
|
|
-- This information is used for detecting the type of potentially
|
|
-- blocking operations described in the ARM 9.5.1, par. 15 (external
|
|
-- calls on a protected subprogram with the same target object as that
|
|
-- of the protected action).
|
|
end record;
|
|
|
|
procedure Finalize_Protection (Object : in out Protection);
|
|
-- Clean up a Protection object (in particular, finalize the associated
|
|
-- Lock object). The compiler generates calls automatically to this
|
|
-- procedure
|
|
|
|
end System.Tasking.Protected_Objects;
|