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