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