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-2009, 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