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 . --
6 -- O P E R A T I O N 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 extended primitives related to
39 -- Protected_Objects with entries.
40 -- The handling of protected objects with no entries is done in
41 -- System.Tasking.Protected_Objects, the simple routines for protected
42 -- objects with entries in System.Tasking.Protected_Objects.Entries.
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.
50 -- used for Exception_Id
52 with System.Tasking.Protected_Objects.Entries;
54 package System.Tasking.Protected_Objects.Operations is
55 pragma Elaborate_Body;
57 type Communication_Block is private;
58 -- Objects of this type are passed between GNARL calls to allow RTS
59 -- information to be preserved.
61 procedure Protected_Entry_Call
62 (Object : Entries.Protection_Entries_Access;
63 E : Protected_Entry_Index;
64 Uninterpreted_Data : System.Address;
66 Block : out Communication_Block);
67 -- Make a protected entry call to the specified object.
68 -- Pend a protected entry call on the protected object represented
69 -- by Object. A pended call is not queued; it may be executed immediately
70 -- or queued, depending on the state of the entry barrier.
73 -- The index representing the entry to be called.
76 -- This will be returned by Next_Entry_Call when this call is serviced.
77 -- It can be used by the compiler to pass information between the
78 -- caller and the server, in particular entry parameters.
81 -- The kind of call to be pended
84 -- Information passed between runtime calls by the compiler
86 procedure Timed_Protected_Entry_Call
87 (Object : Entries.Protection_Entries_Access;
88 E : Protected_Entry_Index;
89 Uninterpreted_Data : System.Address;
92 Entry_Call_Successful : out Boolean);
93 -- Same as the Protected_Entry_Call but with time-out specified.
94 -- This routines is used when we do not use ATC mechanism to implement
97 procedure Service_Entries (Object : Entries.Protection_Entries_Access);
98 pragma Inline (Service_Entries);
100 procedure PO_Service_Entries
102 Object : Entries.Protection_Entries_Access);
103 -- Service all entry queues of the specified object, executing the
104 -- corresponding bodies of any queued entry calls that are waiting
105 -- on True barriers. This is used when the state of a protected
106 -- object may have changed, in particular after the execution of
107 -- the statement sequence of a protected procedure.
108 -- Note that servicing an entry may change the value of one or more
109 -- barriers, so this routine keeps checking barriers until all of
112 -- This must be called with abortion deferred and with the corresponding
115 procedure Complete_Entry_Body (Object : Entries.Protection_Entries_Access);
116 -- Called from within an entry body procedure, indicates that the
117 -- corresponding entry call has been serviced.
119 procedure Exceptional_Complete_Entry_Body
120 (Object : Entries.Protection_Entries_Access;
121 Ex : Ada.Exceptions.Exception_Id);
122 -- Perform all of the functions of Complete_Entry_Body. In addition,
123 -- report in Ex the exception whose propagation terminated the entry
124 -- body to the runtime system.
126 procedure Cancel_Protected_Entry_Call (Block : in out Communication_Block);
127 -- Attempt to cancel the most recent protected entry call. If the call is
128 -- not queued abortably, wait until it is or until it has completed.
129 -- If the call is actually cancelled, the called object will be
130 -- locked on return from this call. Get_Cancelled (Block) can be
131 -- used to determine if the cancellation took place; there
132 -- may be entries needing service in this case.
134 -- Block passes information between this and other runtime calls.
136 function Enqueued (Block : Communication_Block) return Boolean;
137 -- Returns True if the Protected_Entry_Call which returned the
138 -- specified Block object was queued; False otherwise.
140 function Cancelled (Block : Communication_Block) return Boolean;
141 -- Returns True if the Protected_Entry_Call which returned the
142 -- specified Block object was cancelled, False otherwise.
144 procedure Requeue_Protected_Entry
145 (Object : Entries.Protection_Entries_Access;
146 New_Object : Entries.Protection_Entries_Access;
147 E : Protected_Entry_Index;
148 With_Abort : Boolean);
149 -- If Object = New_Object, queue the protected entry call on Object
150 -- currently being serviced on the queue corresponding to the entry
153 -- If Object /= New_Object, transfer the call to New_Object.E,
154 -- executing or queuing it as appropriate.
156 -- With_Abort---True if the call is to be queued abortably, false
159 procedure Requeue_Task_To_Protected_Entry
160 (New_Object : Entries.Protection_Entries_Access;
161 E : Protected_Entry_Index;
162 With_Abort : Boolean);
163 -- Transfer task entry call currently being serviced to entry E
166 -- With_Abort---True if the call is to be queued abortably, false
169 function Protected_Count
170 (Object : Entries.Protection_Entries'Class;
171 E : Protected_Entry_Index)
173 -- Return the number of entry calls to E on Object.
175 function Protected_Entry_Caller
176 (Object : Entries.Protection_Entries'Class) return Task_ID;
177 -- Return value of E'Caller, where E is the protected entry currently
178 -- being handled. This will only work if called from within an entry
179 -- body, as required by the LRM (C.7.1(14)).
181 -- For internal use only:
183 procedure PO_Do_Or_Queue
185 Object : Entries.Protection_Entries_Access;
186 Entry_Call : Entry_Call_Link;
187 With_Abort : Boolean);
188 -- This procedure either executes or queues an entry call, depending
189 -- on the status of the corresponding barrier. It assumes that abortion
190 -- is deferred and that the specified object is locked.
193 type Communication_Block is record
195 Enqueued : Boolean := True;
196 Cancelled : Boolean := False;
198 pragma Volatile (Communication_Block);
201 -- The Communication_Block seems to be a relic.
202 -- At the moment, the compiler seems to be generating
203 -- unnecessary conditional code based on this block.
204 -- See the code generated for async. select with task entry
205 -- call for another way of solving this.
207 end System.Tasking.Protected_Objects.Operations;