1 ------------------------------------------------------------------------------
3 -- GNU ADA RUN-TIME LIBRARY (GNARL) COMPONENTS --
5 -- SYSTEM.TASKING.PROTECTED_OBJECTS.ENTRIES --
9 -- Copyright (C) 1992-2005, 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 2, or (at your option) any later ver- --
14 -- sion. GNARL 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. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNARL; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
20 -- MA 02111-1307, USA. --
22 -- As a special exception, if other files instantiate generics from this --
23 -- unit, or you link this unit with other files to produce an executable, --
24 -- this unit does not by itself cause the resulting executable to be --
25 -- covered by the GNU General Public License. This exception does not --
26 -- however invalidate any other reasons why the executable file might be --
27 -- covered by the GNU Public License. --
29 -- GNARL was developed by the GNARL team at Florida State University. --
30 -- Extensive contributions were provided by Ada Core Technologies, Inc. --
32 ------------------------------------------------------------------------------
34 -- This package contains all the simple primitives related to
35 -- Protected_Objects with entries (i.e init, lock, unlock).
36 -- The handling of protected objects with no entries is done in
37 -- System.Tasking.Protected_Objects, the complex routines for protected
38 -- 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 -- used for Limited_Controlled
48 with Unchecked_Conversion
;
50 package System
.Tasking
.Protected_Objects
.Entries
is
51 pragma Elaborate_Body
;
53 subtype Positive_Protected_Entry_Index
is
54 Protected_Entry_Index
range 1 .. Protected_Entry_Index
'Last;
56 type Find_Body_Index_Access
is access
59 E
: Protected_Entry_Index
)
60 return Protected_Entry_Index
;
62 type Protected_Entry_Body_Array
is
63 array (Positive_Protected_Entry_Index
range <>) of Entry_Body
;
64 -- This is an array of the executable code for all entry bodies of
67 type Protected_Entry_Body_Access
is access all Protected_Entry_Body_Array
;
69 type Protected_Entry_Queue_Array
is
70 array (Protected_Entry_Index
range <>) of Entry_Queue
;
72 -- This type contains the GNARL state of a protected object. The
73 -- application-defined portion of the state (i.e. private objects)
74 -- is maintained by the compiler-generated code.
75 -- note that there is a simplified version of this type declared in
76 -- System.Tasking.PO_Simple that handle the simple case (no entries).
78 type Protection_Entries
(Num_Entries
: Protected_Entry_Index
) is new
79 Ada
.Finalization
.Limited_Controlled
81 L
: aliased Task_Primitives
.Lock
;
82 -- The underlying lock associated with a Protection_Entries.
83 -- Note that you should never (un)lock Object.L directly, but instead
84 -- use Lock_Entries/Unlock_Entries.
86 Compiler_Info
: System
.Address
;
87 -- Pointer to compiler-generated record representing protected object
89 Call_In_Progress
: Entry_Call_Link
;
90 -- Pointer to the entry call being executed (if any)
92 Ceiling
: System
.Any_Priority
;
93 -- Ceiling priority associated with the protected object
96 -- This field contains the protected object's owner. Null_Task
97 -- indicates that the protected object is not currently being used.
98 -- This information is used for detecting the type of potentially
99 -- blocking operations described in the ARM 9.5.1, par. 15 (external
100 -- calls on a protected subprogram with the same target object as that
101 -- of the protected action).
103 Old_Base_Priority
: System
.Any_Priority
;
104 -- Task's base priority when the protected operation was called
106 Pending_Action
: Boolean;
107 -- Flag indicating that priority has been dipped temporarily in order
108 -- to avoid violating the priority ceiling of the lock associated with
109 -- this protected object, in Lock_Server. The flag tells Unlock_Server
110 -- or Unlock_And_Update_Server to restore the old priority to
111 -- Old_Base_Priority. This is needed because of situations (bad
112 -- language design?) where one needs to lock a PO but to do so would
113 -- violate the priority ceiling. For example, this can happen when an
114 -- entry call has been requeued to a lower-priority object, and the
115 -- caller then tries to cancel the call while its own priority is
116 -- higher than the ceiling of the new PO.
118 Finalized
: Boolean := False;
119 -- Set to True by Finalize to make this routine idempotent
121 Entry_Bodies
: Protected_Entry_Body_Access
;
122 -- Pointer to an array containing the executable code for all entry
123 -- bodies of a protected type.
125 -- The following function maps the entry index in a call (which denotes
126 -- the queue to the proper entry) into the body of the entry.
128 Find_Body_Index
: Find_Body_Index_Access
;
129 Entry_Queues
: Protected_Entry_Queue_Array
(1 .. Num_Entries
);
132 -- No default initial values for this type, since call records
133 -- will need to be re-initialized before every use.
135 type Protection_Entries_Access
is access all Protection_Entries
'Class;
136 -- See comments in s-tassta.adb about the implicit call to Current_Master
137 -- generated by this declaration.
139 function To_Address
is
140 new Unchecked_Conversion
(Protection_Entries_Access
, System
.Address
);
141 function To_Protection
is
142 new Unchecked_Conversion
(System
.Address
, Protection_Entries_Access
);
144 function Has_Interrupt_Or_Attach_Handler
145 (Object
: Protection_Entries_Access
) return Boolean;
146 -- Returns True if an Interrupt_Handler or Attach_Handler pragma applies
147 -- to the protected object. That is to say this primitive returns False for
148 -- Protection, but is overriden to return True when interrupt handlers are
149 -- declared so the check required by C.3.1(11) can be implemented in
150 -- System.Tasking.Protected_Objects.Initialize_Protection.
152 procedure Initialize_Protection_Entries
153 (Object
: Protection_Entries_Access
;
154 Ceiling_Priority
: Integer;
155 Compiler_Info
: System
.Address
;
156 Entry_Bodies
: Protected_Entry_Body_Access
;
157 Find_Body_Index
: Find_Body_Index_Access
);
158 -- Initialize the Object parameter so that it can be used by the runtime
159 -- to keep track of the runtime state of a protected object.
161 procedure Lock_Entries
(Object
: Protection_Entries_Access
);
162 -- Lock a protected object for write access. Upon return, the caller owns
163 -- the lock to this object, and no other call to Lock or Lock_Read_Only
164 -- with the same argument will return until the corresponding call to
165 -- Unlock has been made by the caller. Program_Error is raised in case of
166 -- ceiling violation.
168 procedure Lock_Entries
169 (Object
: Protection_Entries_Access
; Ceiling_Violation
: out Boolean);
170 -- Same as above, but return the ceiling violation status instead of
171 -- raising Program_Error.
173 procedure Lock_Read_Only_Entries
(Object
: Protection_Entries_Access
);
174 -- Lock a protected object for read access. Upon return, the caller owns
175 -- the lock for read access, and no other calls to Lock with the same
176 -- argument will return until the corresponding call to Unlock has been
177 -- made by the caller. Other calls to Lock_Read_Only may (but need not)
178 -- return before the call to Unlock, and the corresponding callers will
179 -- also own the lock for read access.
181 -- Note: we are not currently using this interface, it is provided for
182 -- possible future use. At the current time, everyone uses Lock for both
183 -- read and write locks.
185 procedure Unlock_Entries
(Object
: Protection_Entries_Access
);
186 -- Relinquish ownership of the lock for the object represented by the
187 -- Object parameter. If this ownership was for write access, or if it was
188 -- for read access where there are no other read access locks outstanding,
189 -- one (or more, in the case of Lock_Read_Only) of the tasks waiting on
190 -- this lock (if any) will be given the lock and allowed to return from
191 -- the Lock or Lock_Read_Only call.
195 procedure Finalize
(Object
: in out Protection_Entries
);
196 -- Clean up a Protection object; in particular, finalize the associated
199 end System
.Tasking
.Protected_Objects
.Entries
;