1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS --
5 -- SYSTEM.TASKING.PROTECTED_OBJECTS.ENTRIES --
9 -- Copyright (C) 1992-2011, Free Software Foundation, Inc. --
11 -- GNARL is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. --
18 -- As a special exception under Section 7 of GPL version 3, you are granted --
19 -- additional permissions described in the GCC Runtime Library Exception, --
20 -- version 3.1, as published by the Free Software Foundation. --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
27 -- GNARL was developed by the GNARL team at Florida State University. --
28 -- Extensive contributions were provided by Ada Core Technologies, Inc. --
30 ------------------------------------------------------------------------------
32 -- This package contains all simple primitives related to Protected_Objects
33 -- with entries (i.e init, lock, unlock).
35 -- The handling of protected objects with no entries is done in
36 -- System.Tasking.Protected_Objects, the complex routines for protected
37 -- objects with entries in System.Tasking.Protected_Objects.Operations.
39 -- The split between Entries and Operations is needed to break circular
40 -- dependencies inside the run time.
42 -- Note: the compiler generates direct calls to this interface, via Rtsfind.
43 -- Any changes to this interface may require corresponding compiler changes.
45 with Ada
.Finalization
;
46 with Ada
.Unchecked_Conversion
;
48 package System
.Tasking
.Protected_Objects
.Entries
is
49 pragma Elaborate_Body
;
51 subtype Positive_Protected_Entry_Index
is
52 Protected_Entry_Index
range 1 .. Protected_Entry_Index
'Last;
54 type Find_Body_Index_Access
is access
57 E
: Protected_Entry_Index
)
58 return Protected_Entry_Index
;
60 type Protected_Entry_Body_Array
is
61 array (Positive_Protected_Entry_Index
range <>) of Entry_Body
;
62 -- This is an array of the executable code for all entry bodies of
65 type Protected_Entry_Body_Access
is access all Protected_Entry_Body_Array
;
67 type Protected_Entry_Queue_Array
is
68 array (Protected_Entry_Index
range <>) of Entry_Queue
;
70 -- This type contains the GNARL state of a protected object. The
71 -- application-defined portion of the state (i.e. private objects)
72 -- is maintained by the compiler-generated code.
73 -- note that there is a simplified version of this type declared in
74 -- System.Tasking.PO_Simple that handle the simple case (no entries).
76 type Protection_Entries
(Num_Entries
: Protected_Entry_Index
) is new
77 Ada
.Finalization
.Limited_Controlled
79 L
: aliased Task_Primitives
.Lock
;
80 -- The underlying lock associated with a Protection_Entries.
81 -- Note that you should never (un)lock Object.L directly, but instead
82 -- use Lock_Entries/Unlock_Entries.
84 Compiler_Info
: System
.Address
;
85 -- Pointer to compiler-generated record representing protected object
87 Call_In_Progress
: Entry_Call_Link
;
88 -- Pointer to the entry call being executed (if any)
90 Ceiling
: System
.Any_Priority
;
91 -- Ceiling priority associated with the protected object
93 New_Ceiling
: System
.Any_Priority
;
94 -- New ceiling priority associated to the protected object. In case
95 -- of assignment of a new ceiling priority to the protected object the
96 -- frontend generates a call to set_ceiling to save the new value in
97 -- this field. After such assignment this value can be read by means
98 -- of the 'Priority attribute, which generates a call to get_ceiling.
99 -- However, the ceiling of the protected object will not be changed
100 -- until completion of the protected action in which the assignment
101 -- has been executed (AARM D.5.2 (10/2)).
104 -- This field contains the protected object's owner. Null_Task
105 -- indicates that the protected object is not currently being used.
106 -- This information is used for detecting the type of potentially
107 -- blocking operations described in the ARM 9.5.1, par. 15 (external
108 -- calls on a protected subprogram with the same target object as that
109 -- of the protected action).
111 Old_Base_Priority
: System
.Any_Priority
;
112 -- Task's base priority when the protected operation was called
114 Pending_Action
: Boolean;
115 -- Flag indicating that priority has been dipped temporarily in order
116 -- to avoid violating the priority ceiling of the lock associated with
117 -- this protected object, in Lock_Server. The flag tells Unlock_Server
118 -- or Unlock_And_Update_Server to restore the old priority to
119 -- Old_Base_Priority. This is needed because of situations (bad
120 -- language design?) where one needs to lock a PO but to do so would
121 -- violate the priority ceiling. For example, this can happen when an
122 -- entry call has been requeued to a lower-priority object, and the
123 -- caller then tries to cancel the call while its own priority is
124 -- higher than the ceiling of the new PO.
126 Finalized
: Boolean := False;
127 -- Set to True by Finalize to make this routine idempotent
129 Entry_Bodies
: Protected_Entry_Body_Access
;
130 -- Pointer to an array containing the executable code for all entry
131 -- bodies of a protected type.
133 Find_Body_Index
: Find_Body_Index_Access
;
134 -- A function which maps the entry index in a call (which denotes the
135 -- queue of the proper entry) into the body of the entry.
137 Entry_Queues
: Protected_Entry_Queue_Array
(1 .. Num_Entries
);
139 Entry_Names
: Entry_Names_Array_Access
:= null;
140 -- An array of string names which denotes entry [family member] names.
141 -- The structure is indexed by protected entry index and contains Num_
142 -- Entries components.
145 -- No default initial values for this type, since call records
146 -- will need to be re-initialized before every use.
148 type Protection_Entries_Access
is access all Protection_Entries
'Class;
149 -- See comments in s-tassta.adb about the implicit call to Current_Master
150 -- generated by this declaration.
152 function To_Address
is
153 new Ada
.Unchecked_Conversion
(Protection_Entries_Access
, System
.Address
);
154 function To_Protection
is
155 new Ada
.Unchecked_Conversion
(System
.Address
, Protection_Entries_Access
);
158 (Object
: Protection_Entries_Access
) return System
.Any_Priority
;
159 -- Returns the new ceiling priority of the protected object
161 function Has_Interrupt_Or_Attach_Handler
162 (Object
: Protection_Entries_Access
) return Boolean;
163 -- Returns True if an Interrupt_Handler or Attach_Handler pragma applies
164 -- to the protected object. That is to say this primitive returns False for
165 -- Protection, but is overridden to return True when interrupt handlers are
166 -- declared so the check required by C.3.1(11) can be implemented in
167 -- System.Tasking.Protected_Objects.Initialize_Protection.
169 procedure Initialize_Protection_Entries
170 (Object
: Protection_Entries_Access
;
171 Ceiling_Priority
: Integer;
172 Compiler_Info
: System
.Address
;
173 Entry_Bodies
: Protected_Entry_Body_Access
;
174 Find_Body_Index
: Find_Body_Index_Access
;
175 Build_Entry_Names
: Boolean);
176 -- Initialize the Object parameter so that it can be used by the runtime
177 -- to keep track of the runtime state of a protected object.
179 procedure Lock_Entries
(Object
: Protection_Entries_Access
);
180 -- Lock a protected object for write access. Upon return, the caller owns
181 -- the lock to this object, and no other call to Lock or Lock_Read_Only
182 -- with the same argument will return until the corresponding call to
183 -- Unlock has been made by the caller. Program_Error is raised in case of
184 -- ceiling violation.
186 procedure Lock_Entries_With_Status
187 (Object
: Protection_Entries_Access
;
188 Ceiling_Violation
: out Boolean);
189 -- Same as above, but return the ceiling violation status instead of
190 -- raising Program_Error.
192 procedure Lock_Read_Only_Entries
(Object
: Protection_Entries_Access
);
193 -- Lock a protected object for read access. Upon return, the caller owns
194 -- the lock for read access, and no other calls to Lock with the same
195 -- argument will return until the corresponding call to Unlock has been
196 -- made by the caller. Other calls to Lock_Read_Only may (but need not)
197 -- return before the call to Unlock, and the corresponding callers will
198 -- also own the lock for read access.
200 -- Note: we are not currently using this interface, it is provided for
201 -- possible future use. At the current time, everyone uses Lock for both
202 -- read and write locks.
204 procedure Set_Ceiling
205 (Object
: Protection_Entries_Access
;
206 Prio
: System
.Any_Priority
);
207 -- Sets the new ceiling priority of the protected object
209 procedure Set_Entry_Name
210 (Object
: Protection_Entries
'Class;
211 Pos
: Protected_Entry_Index
;
212 Val
: String_Access
);
213 -- This is called by the compiler to map a string which denotes an entry
214 -- name to a protected entry index.
216 procedure Unlock_Entries
(Object
: Protection_Entries_Access
);
217 -- Relinquish ownership of the lock for the object represented by the
218 -- Object parameter. If this ownership was for write access, or if it was
219 -- for read access where there are no other read access locks outstanding,
220 -- one (or more, in the case of Lock_Read_Only) of the tasks waiting on
221 -- this lock (if any) will be given the lock and allowed to return from
222 -- the Lock or Lock_Read_Only call.
226 overriding
procedure Finalize
(Object
: in out Protection_Entries
);
227 -- Clean up a Protection object; in particular, finalize the associated
230 end System
.Tasking
.Protected_Objects
.Entries
;