1 ------------------------------------------------------------------------------
3 -- GNU ADA RUN-TIME LIBRARY (GNARL) COMPONENTS --
5 -- SYSTEM.TASKING.PROTECTED_OBJECTS.ENTRIES --
11 -- Copyright (C) 1992-2001, Free Software Foundation, Inc. --
13 -- GNARL is free software; you can redistribute it and/or modify it under --
14 -- terms of the GNU General Public License as published by the Free Soft- --
15 -- ware Foundation; either version 2, or (at your option) any later ver- --
16 -- sion. GNARL is distributed in the hope that it will be useful, but WITH- --
17 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
18 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
19 -- for more details. You should have received a copy of the GNU General --
20 -- Public License distributed with GNARL; see file COPYING. If not, write --
21 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
22 -- MA 02111-1307, USA. --
24 -- As a special exception, if other files instantiate generics from this --
25 -- unit, or you link this unit with other files to produce an executable, --
26 -- this unit does not by itself cause the resulting executable to be --
27 -- covered by the GNU General Public License. This exception does not --
28 -- however invalidate any other reasons why the executable file might be --
29 -- covered by the GNU Public License. --
31 -- GNARL was developed by the GNARL team at Florida State University. It is --
32 -- now maintained by Ada Core Technologies Inc. in cooperation with Florida --
33 -- State University (http://www.gnat.com). --
35 ------------------------------------------------------------------------------
37 -- This package contains all the simple primitives related to
38 -- Protected_Objects with entries (i.e init, lock, unlock).
39 -- The handling of protected objects with no entries is done in
40 -- System.Tasking.Protected_Objects, the complex routines for protected
41 -- objects with entries in System.Tasking.Protected_Objects.Operations.
42 -- The split between Entries and Operations is needed to break circular
43 -- dependencies inside the run time.
45 -- Note: the compiler generates direct calls to this interface, via Rtsfind.
46 -- Any changes to this interface may require corresponding compiler changes.
48 with Ada.Finalization;
49 -- used for Limited_Controlled
51 with Unchecked_Conversion;
53 package System.Tasking.Protected_Objects.Entries is
54 pragma Elaborate_Body;
56 subtype Positive_Protected_Entry_Index is
57 Protected_Entry_Index range 1 .. Protected_Entry_Index'Last;
59 type Find_Body_Index_Access is access
62 E : Protected_Entry_Index)
63 return Protected_Entry_Index;
65 type Protected_Entry_Body_Array is
66 array (Positive_Protected_Entry_Index range <>) of Entry_Body;
67 -- This is an array of the executable code for all entry bodies of
70 type Protected_Entry_Body_Access is access all Protected_Entry_Body_Array;
72 type Protected_Entry_Queue_Array is
73 array (Protected_Entry_Index range <>) of Entry_Queue;
75 -- This type contains the GNARL state of a protected object. The
76 -- application-defined portion of the state (i.e. private objects)
77 -- is maintained by the compiler-generated code.
78 -- note that there is a simplified version of this type declared in
79 -- System.Tasking.PO_Simple that handle the simple case (no entries).
81 type Protection_Entries (Num_Entries : Protected_Entry_Index) is new
82 Ada.Finalization.Limited_Controlled
84 L : aliased Task_Primitives.Lock;
85 -- The underlying lock associated with a Protection_Entries.
86 -- Note that you should never (un)lock Object.L directly, but instead
87 -- use Lock_Entries/Unlock_Entries.
89 Compiler_Info : System.Address;
90 Call_In_Progress : Entry_Call_Link;
91 Ceiling : System.Any_Priority;
92 Old_Base_Priority : System.Any_Priority;
93 Pending_Action : Boolean;
94 -- Flag indicating that priority has been dipped temporarily
95 -- in order to avoid violating the priority ceiling of the lock
96 -- associated with this protected object, in Lock_Server.
97 -- The flag tells Unlock_Server or Unlock_And_Update_Server to
98 -- restore the old priority to Old_Base_Priority. This is needed
99 -- because of situations (bad language design?) where one
100 -- needs to lock a PO but to do so would violate the priority
101 -- ceiling. For example, this can happen when an entry call
102 -- has been requeued to a lower-priority object, and the caller
103 -- then tries to cancel the call while its own priority is higher
104 -- than the ceiling of the new PO.
105 Finalized : Boolean := False;
106 -- Set to True by Finalize to make this routine idempotent.
108 Entry_Bodies : Protected_Entry_Body_Access;
110 -- The following function maps the entry index in a call (which denotes
111 -- the queue to the proper entry) into the body of the entry.
113 Find_Body_Index : Find_Body_Index_Access;
114 Entry_Queues : Protected_Entry_Queue_Array (1 .. Num_Entries);
116 pragma Volatile (Protection_Entries);
118 -- No default initial values for this type, since call records
119 -- will need to be re-initialized before every use.
121 type Protection_Entries_Access is access all Protection_Entries'Class;
122 -- See comments in s-tassta.adb about the implicit call to Current_Master
123 -- generated by this declaration.
125 function To_Protection_Entries is new Unchecked_Conversion
126 (Protection_Access, Protection_Entries_Access);
128 function To_Address is
129 new Unchecked_Conversion (Protection_Entries_Access, System.Address);
130 function To_Protection is
131 new Unchecked_Conversion (System.Address, Protection_Entries_Access);
133 function Has_Interrupt_Or_Attach_Handler
134 (Object : Protection_Entries_Access) return Boolean;
135 -- Returns True if an Interrupt_Handler or Attach_Handler pragma applies
136 -- to the protected object. That is to say this primitive returns False for
137 -- Protection, but is overriden to return True when interrupt handlers are
138 -- declared so the check required by C.3.1(11) can be implemented in
139 -- System.Tasking.Protected_Objects.Initialize_Protection.
141 procedure Initialize_Protection_Entries
142 (Object : Protection_Entries_Access;
143 Ceiling_Priority : Integer;
144 Compiler_Info : System.Address;
145 Entry_Bodies : Protected_Entry_Body_Access;
146 Find_Body_Index : Find_Body_Index_Access);
147 -- Initialize the Object parameter so that it can be used by the runtime
148 -- to keep track of the runtime state of a protected object.
150 procedure Lock_Entries (Object : Protection_Entries_Access);
151 -- Lock a protected object for write access. Upon return, the caller
152 -- owns the lock to this object, and no other call to Lock or
153 -- Lock_Read_Only with the same argument will return until the
154 -- corresponding call to Unlock has been made by the caller.
155 -- Program_Error is raised in case of ceiling violation.
157 procedure Lock_Entries
158 (Object : Protection_Entries_Access; Ceiling_Violation : out Boolean);
159 -- Same as above, but return the ceiling violation status instead of
160 -- raising Program_Error.
162 procedure Lock_Read_Only_Entries (Object : Protection_Entries_Access);
163 -- Lock a protected object for read access. Upon return, the caller
164 -- owns the lock for read access, and no other calls to Lock with the
165 -- same argument will return until the corresponding call to Unlock
166 -- has been made by the caller. Other calls to Lock_Read_Only may (but
167 -- need not) return before the call to Unlock, and the corresponding
168 -- callers will also own the lock for read access.
170 -- Note: we are not currently using this interface, it is provided
171 -- for possible future use. At the current time, everyone uses Lock
172 -- for both read and write locks.
174 procedure Unlock_Entries (Object : Protection_Entries_Access);
175 -- Relinquish ownership of the lock for the object represented by
176 -- the Object parameter. If this ownership was for write access, or
177 -- if it was for read access where there are no other read access
178 -- locks outstanding, one (or more, in the case of Lock_Read_Only)
179 -- of the tasks waiting on this lock (if any) will be given the
180 -- lock and allowed to return from the Lock or Lock_Read_Only call.
184 procedure Finalize (Object : in out Protection_Entries);
185 -- Clean up a Protection object; in particular, finalize the associated
188 end System.Tasking.Protected_Objects.Entries;