1------------------------------------------------------------------------------ 2-- -- 3-- GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS -- 4-- -- 5-- SYSTEM.TASKING.PROTECTED_OBJECTS.OPERATIONS -- 6-- -- 7-- S p e c -- 8-- -- 9-- Copyright (C) 1992-2019, Free Software Foundation, Inc. -- 10-- -- 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. -- 17-- -- 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. -- 21-- -- 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/>. -- 26-- -- 27-- GNARL was developed by the GNARL team at Florida State University. -- 28-- Extensive contributions were provided by Ada Core Technologies, Inc. -- 29-- -- 30------------------------------------------------------------------------------ 31 32-- This package contains all the extended primitives related to protected 33-- objects with entries. 34 35-- The handling of protected objects with no entries is done in 36-- System.Tasking.Protected_Objects, the simple routines for protected 37-- objects with entries in System.Tasking.Protected_Objects.Entries. The 38-- split between Entries and Operations is needed to break circular 39-- dependencies inside the run time. 40 41-- Note: the compiler generates direct calls to this interface, via Rtsfind. 42-- Any changes to this interface may require corresponding compiler changes. 43 44with Ada.Exceptions; 45 46with System.Tasking.Protected_Objects.Entries; 47 48package System.Tasking.Protected_Objects.Operations is 49 pragma Elaborate_Body; 50 51 type Communication_Block is private; 52 -- Objects of this type are passed between GNARL calls to allow RTS 53 -- information to be preserved. 54 55 procedure Protected_Entry_Call 56 (Object : Entries.Protection_Entries_Access; 57 E : Protected_Entry_Index; 58 Uninterpreted_Data : System.Address; 59 Mode : Call_Modes; 60 Block : out Communication_Block); 61 -- Make a protected entry call to the specified object. 62 -- Pend a protected entry call on the protected object represented 63 -- by Object. A pended call is not queued; it may be executed immediately 64 -- or queued, depending on the state of the entry barrier. 65 -- 66 -- E 67 -- The index representing the entry to be called. 68 -- 69 -- Uninterpreted_Data 70 -- This will be returned by Next_Entry_Call when this call is serviced. 71 -- It can be used by the compiler to pass information between the 72 -- caller and the server, in particular entry parameters. 73 -- 74 -- Mode 75 -- The kind of call to be pended 76 -- 77 -- Block 78 -- Information passed between runtime calls by the compiler 79 80 procedure Timed_Protected_Entry_Call 81 (Object : Entries.Protection_Entries_Access; 82 E : Protected_Entry_Index; 83 Uninterpreted_Data : System.Address; 84 Timeout : Duration; 85 Mode : Delay_Modes; 86 Entry_Call_Successful : out Boolean); 87 -- Same as the Protected_Entry_Call but with time-out specified. 88 -- This routines is used when we do not use ATC mechanism to implement 89 -- timed entry calls. 90 91 procedure Service_Entries (Object : Entries.Protection_Entries_Access); 92 pragma Inline (Service_Entries); 93 94 procedure PO_Service_Entries 95 (Self_ID : Task_Id; 96 Object : Entries.Protection_Entries_Access; 97 Unlock_Object : Boolean := True); 98 -- Service all entry queues of the specified object, executing the 99 -- corresponding bodies of any queued entry calls that are waiting 100 -- on True barriers. This is used when the state of a protected 101 -- object may have changed, in particular after the execution of 102 -- the statement sequence of a protected procedure. 103 -- 104 -- Note that servicing an entry may change the value of one or more 105 -- barriers, so this routine keeps checking barriers until all of 106 -- them are closed. 107 -- 108 -- This must be called with abort deferred and with the corresponding 109 -- object locked. 110 -- 111 -- If Unlock_Object is set True, then Object is unlocked on return, 112 -- otherwise Object remains locked and the caller is responsible for 113 -- the required unlock. 114 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. 118 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. 125 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. 133 -- 134 -- Block passes information between this and other runtime calls. 135 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. 139 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. 143 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 151 -- represented by E. 152 -- 153 -- If Object /= New_Object, transfer the call to New_Object.E, 154 -- executing or queuing it as appropriate. 155 -- 156 -- With_Abort---True if the call is to be queued abortably, false 157 -- otherwise. 158 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 164 -- on New_Object. 165 -- 166 -- With_Abort---True if the call is to be queued abortably, false 167 -- otherwise. 168 169 function Protected_Count 170 (Object : Entries.Protection_Entries'Class; 171 E : Protected_Entry_Index) 172 return Natural; 173 -- Return the number of entry calls to E on Object 174 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)). 180 181 -- For internal use only 182 183 procedure PO_Do_Or_Queue 184 (Self_ID : Task_Id; 185 Object : Entries.Protection_Entries_Access; 186 Entry_Call : Entry_Call_Link); 187 -- This procedure either executes or queues an entry call, depending 188 -- on the status of the corresponding barrier. It assumes that abort 189 -- is deferred and that the specified object is locked. 190 191private 192 type Communication_Block is record 193 Self : Task_Id; 194 Enqueued : Boolean := True; 195 Cancelled : Boolean := False; 196 end record; 197 pragma Volatile (Communication_Block); 198 199 -- When a program contains limited interfaces, the compiler generates the 200 -- predefined primitives associated with dispatching selects. One of the 201 -- parameters of these routines is of type Communication_Block. Even if 202 -- the program lacks implementing concurrent types, the tasking runtime is 203 -- dragged in unconditionally because of Communication_Block. To avoid this 204 -- case, the compiler uses type Dummy_Communication_Block which defined in 205 -- System.Soft_Links. If the structure of Communication_Block is changed, 206 -- the corresponding dummy type must be changed as well. 207 208 -- The Communication_Block seems to be a relic. At the moment, the 209 -- compiler seems to be generating unnecessary conditional code based on 210 -- this block. See the code generated for async. select with task entry 211 -- call for another way of solving this ??? 212 213end System.Tasking.Protected_Objects.Operations; 214