| ------------------------------------------------------------------------------ |
| -- -- |
| -- GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS -- |
| -- -- |
| -- SYSTEM.TASKING.PROTECTED_OBJECTS.OPERATIONS -- |
| -- -- |
| -- S p e c -- |
| -- -- |
| -- Copyright (C) 1992-2022, Free Software Foundation, Inc. -- |
| -- -- |
| -- GNARL is free software; you can redistribute it and/or modify it under -- |
| -- terms of the GNU General Public License as published by the Free Soft- -- |
| -- ware Foundation; either version 3, or (at your option) any later ver- -- |
| -- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- |
| -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- |
| -- or FITNESS FOR A PARTICULAR PURPOSE. -- |
| -- -- |
| -- As a special exception under Section 7 of GPL version 3, you are granted -- |
| -- additional permissions described in the GCC Runtime Library Exception, -- |
| -- version 3.1, as published by the Free Software Foundation. -- |
| -- -- |
| -- You should have received a copy of the GNU General Public License and -- |
| -- a copy of the GCC Runtime Library Exception along with this program; -- |
| -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see -- |
| -- <http://www.gnu.org/licenses/>. -- |
| -- -- |
| -- GNARL was developed by the GNARL team at Florida State University. -- |
| -- Extensive contributions were provided by Ada Core Technologies, Inc. -- |
| -- -- |
| ------------------------------------------------------------------------------ |
| |
| -- This package contains all the extended primitives related to protected |
| -- objects with entries. |
| |
| -- The handling of protected objects with no entries is done in |
| -- System.Tasking.Protected_Objects, the simple routines for protected |
| -- objects with entries in System.Tasking.Protected_Objects.Entries. The |
| -- split between Entries and Operations is needed to break circular |
| -- dependencies inside the run time. |
| |
| -- Note: the compiler generates direct calls to this interface, via Rtsfind. |
| -- Any changes to this interface may require corresponding compiler changes. |
| |
| with Ada.Exceptions; |
| |
| with System.Tasking.Protected_Objects.Entries; |
| |
| package System.Tasking.Protected_Objects.Operations is |
| pragma Elaborate_Body; |
| |
| type Communication_Block is private; |
| -- Objects of this type are passed between GNARL calls to allow RTS |
| -- information to be preserved. |
| |
| procedure Protected_Entry_Call |
| (Object : Entries.Protection_Entries_Access; |
| E : Protected_Entry_Index; |
| Uninterpreted_Data : System.Address; |
| Mode : Call_Modes; |
| Block : out Communication_Block); |
| -- Make a protected entry call to the specified object. |
| -- Pend a protected entry call on the protected object represented |
| -- by Object. A pended call is not queued; it may be executed immediately |
| -- or queued, depending on the state of the entry barrier. |
| -- |
| -- E |
| -- The index representing the entry to be called. |
| -- |
| -- Uninterpreted_Data |
| -- This will be returned by Next_Entry_Call when this call is serviced. |
| -- It can be used by the compiler to pass information between the |
| -- caller and the server, in particular entry parameters. |
| -- |
| -- Mode |
| -- The kind of call to be pended |
| -- |
| -- Block |
| -- Information passed between runtime calls by the compiler |
| |
| procedure Timed_Protected_Entry_Call |
| (Object : Entries.Protection_Entries_Access; |
| E : Protected_Entry_Index; |
| Uninterpreted_Data : System.Address; |
| Timeout : Duration; |
| Mode : Delay_Modes; |
| Entry_Call_Successful : out Boolean); |
| -- Same as the Protected_Entry_Call but with time-out specified. |
| -- This routines is used when we do not use ATC mechanism to implement |
| -- timed entry calls. |
| |
| procedure Service_Entries (Object : Entries.Protection_Entries_Access); |
| pragma Inline (Service_Entries); |
| |
| procedure PO_Service_Entries |
| (Self_ID : Task_Id; |
| Object : Entries.Protection_Entries_Access; |
| Unlock_Object : Boolean := True); |
| -- Service all entry queues of the specified object, executing the |
| -- corresponding bodies of any queued entry calls that are waiting |
| -- on True barriers. This is used when the state of a protected |
| -- object may have changed, in particular after the execution of |
| -- the statement sequence of a protected procedure. |
| -- |
| -- Note that servicing an entry may change the value of one or more |
| -- barriers, so this routine keeps checking barriers until all of |
| -- them are closed. |
| -- |
| -- This must be called with abort deferred and with the corresponding |
| -- object locked. |
| -- |
| -- If Unlock_Object is set True, then Object is unlocked on return, |
| -- otherwise Object remains locked and the caller is responsible for |
| -- the required unlock. |
| |
| procedure Complete_Entry_Body (Object : Entries.Protection_Entries_Access); |
| -- Called from within an entry body procedure, indicates that the |
| -- corresponding entry call has been serviced. |
| |
| procedure Exceptional_Complete_Entry_Body |
| (Object : Entries.Protection_Entries_Access; |
| Ex : Ada.Exceptions.Exception_Id); |
| -- Perform all of the functions of Complete_Entry_Body. In addition, |
| -- report in Ex the exception whose propagation terminated the entry |
| -- body to the runtime system. |
| |
| procedure Cancel_Protected_Entry_Call (Block : in out Communication_Block); |
| -- Attempt to cancel the most recent protected entry call. If the call is |
| -- not queued abortably, wait until it is or until it has completed. |
| -- If the call is actually cancelled, the called object will be |
| -- locked on return from this call. Get_Cancelled (Block) can be |
| -- used to determine if the cancellation took place; there |
| -- may be entries needing service in this case. |
| -- |
| -- Block passes information between this and other runtime calls. |
| |
| function Enqueued (Block : Communication_Block) return Boolean; |
| -- Returns True if the Protected_Entry_Call which returned the |
| -- specified Block object was queued; False otherwise. |
| |
| function Cancelled (Block : Communication_Block) return Boolean; |
| -- Returns True if the Protected_Entry_Call which returned the |
| -- specified Block object was cancelled, False otherwise. |
| |
| procedure Requeue_Protected_Entry |
| (Object : Entries.Protection_Entries_Access; |
| New_Object : Entries.Protection_Entries_Access; |
| E : Protected_Entry_Index; |
| With_Abort : Boolean); |
| -- If Object = New_Object, queue the protected entry call on Object |
| -- currently being serviced on the queue corresponding to the entry |
| -- represented by E. |
| -- |
| -- If Object /= New_Object, transfer the call to New_Object.E, |
| -- executing or queuing it as appropriate. |
| -- |
| -- With_Abort---True if the call is to be queued abortably, false |
| -- otherwise. |
| |
| procedure Requeue_Task_To_Protected_Entry |
| (New_Object : Entries.Protection_Entries_Access; |
| E : Protected_Entry_Index; |
| With_Abort : Boolean); |
| -- Transfer task entry call currently being serviced to entry E |
| -- on New_Object. |
| -- |
| -- With_Abort---True if the call is to be queued abortably, false |
| -- otherwise. |
| |
| function Protected_Count |
| (Object : Entries.Protection_Entries'Class; |
| E : Protected_Entry_Index) |
| return Natural; |
| -- Return the number of entry calls to E on Object |
| |
| function Protected_Entry_Caller |
| (Object : Entries.Protection_Entries'Class) return Task_Id; |
| -- Return value of E'Caller, where E is the protected entry currently |
| -- being handled. This will only work if called from within an entry |
| -- body, as required by the LRM (C.7.1(14)). |
| |
| -- For internal use only |
| |
| procedure PO_Do_Or_Queue |
| (Self_ID : Task_Id; |
| Object : Entries.Protection_Entries_Access; |
| Entry_Call : Entry_Call_Link); |
| -- This procedure either executes or queues an entry call, depending |
| -- on the status of the corresponding barrier. It assumes that abort |
| -- is deferred and that the specified object is locked. |
| |
| private |
| type Communication_Block is record |
| Self : Task_Id; |
| Enqueued : Boolean := True; |
| Cancelled : Boolean := False; |
| end record; |
| pragma Volatile (Communication_Block); |
| |
| -- When a program contains limited interfaces, the compiler generates the |
| -- predefined primitives associated with dispatching selects. One of the |
| -- parameters of these routines is of type Communication_Block. Even if |
| -- the program lacks implementing concurrent types, the tasking runtime is |
| -- dragged in unconditionally because of Communication_Block. To avoid this |
| -- case, the compiler uses type Dummy_Communication_Block which defined in |
| -- System.Soft_Links. If the structure of Communication_Block is changed, |
| -- the corresponding dummy type must be changed as well. |
| |
| -- The Communication_Block seems to be a relic. At the moment, the |
| -- compiler seems to be generating unnecessary conditional code based on |
| -- this block. See the code generated for async. select with task entry |
| -- call for another way of solving this ??? |
| |
| end System.Tasking.Protected_Objects.Operations; |
