gcc/ada/s-tasren.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                GNU ADA RUN-TIME LIBRARY (GNARL) COMPONENTS               --
   4 --                                                                          --
   5 --             S Y S T E M . T A S K I N G . R E N D E Z V O U S            --
   6 --                                                                          --
   7 --                                  S p e c                                 --
   8 --                                                                          --
   9 --                             $Revision$
  10 --                                                                          --
  11 --          Copyright (C) 1992-2001, Free Software Foundation, Inc.         --
  12 --                                                                          --
  13 -- GNARL is free software; you can  redistribute it  and/or modify it under --
  14 -- terms of the  GNU General Public License as published  by the Free Soft- --
  15 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  16 -- sion. GNARL is distributed in the hope that it will be useful, but WITH- --
  17 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  18 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  19 -- for  more details.  You should have  received  a copy of the GNU General --
  20 -- Public License  distributed with GNARL; see file COPYING.  If not, write --
  21 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  22 -- MA 02111-1307, USA.                                                      --
  23 --                                                                          --
  24 -- As a special exception,  if other files  instantiate  generics from this --
  25 -- unit, or you link  this unit with other files  to produce an executable, --
  26 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  27 -- covered  by the  GNU  General  Public  License.  This exception does not --
  28 -- however invalidate  any other reasons why  the executable file  might be --
  29 -- covered by the  GNU Public License.                                      --
  30 --                                                                          --
  31 -- GNARL was developed by the GNARL team at Florida State University. It is --
  32 -- now maintained by Ada Core Technologies, Inc. (http://www.gnat.com).     --
  33 --                                                                          --
  34 ------------------------------------------------------------------------------
  35
  36 --  Note: the compiler generates direct calls to this interface, via Rtsfind.
  37 --  Any changes to this interface may require corresponding compiler changes.
  38
  39 with Ada.Exceptions;
  40 --  Used for, Exception_Id
  41
  42 with System.Tasking.Protected_Objects.Entries;
  43 --  used for Protection_Entries
  44
  45 package System.Tasking.Rendezvous is
  46
  47    package STPE renames System.Tasking.Protected_Objects.Entries;
  48
  49    procedure Task_Entry_Call
  50      (Acceptor              : Task_ID;
  51       E                     : Task_Entry_Index;
  52       Uninterpreted_Data    : System.Address;
  53       Mode                  : Call_Modes;
  54       Rendezvous_Successful : out Boolean);
  55    --  General entry call used to implement ATC or conditional entry calls.
  56    --  Compiler interface only. Do not call from within the RTS.
  57    --  Acceptor is the ID of the acceptor task.
  58    --  E is the entry index requested.
  59    --  Uninterpreted_Data represents the parameters of the entry. It is
  60    --  constructed by the compiler for the caller and the callee; therefore,
  61    --  the run time never needs to decode this data.
  62    --  Mode can be either Asynchronous_Call (ATC) or Conditional_Call.
  63    --  Rendezvous_Successful is set to True on return if the call was serviced.
  64
  65    procedure Timed_Task_Entry_Call
  66      (Acceptor              : Task_ID;
  67       E                     : Task_Entry_Index;
  68       Uninterpreted_Data    : System.Address;
  69       Timeout               : Duration;
  70       Mode                  : Delay_Modes;
  71       Rendezvous_Successful : out Boolean);
  72    --  Timed entry call without using ATC.
  73    --  Compiler interface only. Do not call from within the RTS.
  74    --  See Task_Entry_Call for details on Acceptor, E and Uninterpreted_Data.
  75    --  Timeout is the value of the time out.
  76    --  Mode determines whether the delay is relative or absolute.
  77
  78    procedure Call_Simple
  79      (Acceptor           : Task_ID;
  80       E                  : Task_Entry_Index;
  81       Uninterpreted_Data : System.Address);
  82    --  Simple entry call.
  83    --  Compiler interface only. Do not call from within the RTS.
  84    --
  85    --  source:
  86    --     T.E1 (Params);
  87    --
  88    --  expansion:
  89    --    declare
  90    --       P : parms := (parm1, parm2, parm3);
  91    --       X : Task_Entry_Index := 1;
  92    --    begin
  93    --       Call_Simple (t._task_id, X, P'Address);
  94    --       parm1 := P.param1;
  95    --       parm2 := P.param2;
  96    --       ...
  97    --    end;
  98
  99    procedure Cancel_Task_Entry_Call (Cancelled : out Boolean);
 100    --  Cancel pending asynchronous task entry call.
 101    --  Compiler interface only. Do not call from within the RTS.
 102    --  See Exp_Ch9.Expand_N_Asynchronous_Select for code expansion.
 103
 104    procedure Requeue_Task_Entry
 105      (Acceptor   : Task_ID;
 106       E          : Task_Entry_Index;
 107       With_Abort : Boolean);
 108    --  Requeue from a task entry to a task entry.
 109    --  Compiler interface only. Do not call from within the RTS.
 110    --  The code generation for task entry requeues is different from that for
 111    --  protected entry requeues. There is a "goto" that skips around the call
 112    --  to Complete_Rendezvous, so that Requeue_Task_Entry must also do the work
 113    --  of Complete_Rendezvous. The difference is that it does not report that
 114    --  the call's State = Done.
 115    --
 116    --  source:
 117    --     accept e1 do
 118    --       ...A...
 119    --       requeue e2;
 120    --       ...B...
 121    --     end e1;
 122    --
 123    --  expansion:
 124    --     A62b : address;
 125    --     L61b : label
 126    --     begin
 127    --        accept_call (1, A62b);
 128    --        ...A...
 129    --        requeue_task_entry (tTV!(t)._task_id, 2, false);
 130    --        goto L61b;
 131    --        ...B...
 132    --        complete_rendezvous;
 133    --        <<L61b>>
 134    --     exception
 135    --        when others =>
 136    --           exceptional_complete_rendezvous (current_exception);
 137    --     end;
 138
 139    procedure Requeue_Protected_To_Task_Entry
 140      (Object     : STPE.Protection_Entries_Access;
 141       Acceptor   : Task_ID;
 142       E          : Task_Entry_Index;
 143       With_Abort : Boolean);
 144    --  Requeue from a protected entry to a task entry.
 145    --  Compiler interface only. Do not call from within the RTS.
 146    --
 147    --  source:
 148    --     entry e2 when b is
 149    --     begin
 150    --        b := false;
 151    --        ...A...
 152    --        requeue t.e2;
 153    --     end e2;
 154    --
 155    --  expansion:
 156    --     procedure rPT__E14b (O : address; P : address; E :
 157    --       protected_entry_index) is
 158    --        type rTVP is access rTV;
 159    --        freeze rTVP []
 160    --        _object : rTVP := rTVP!(O);
 161    --     begin
 162    --        declare
 163    --           rR : protection renames _object._object;
 164    --           vP : integer renames _object.v;
 165    --           bP : boolean renames _object.b;
 166    --        begin
 167    --           b := false;
 168    --           ...A...
 169    --           requeue_protected_to_task_entry (rR'unchecked_access, tTV!(t).
 170    --             _task_id, 2, false);
 171    --           return;
 172    --        end;
 173    --        complete_entry_body (_object._object'unchecked_access, objectF =>
 174    --          0);
 175    --        return;
 176    --     exception
 177    --        when others =>
 178    --           abort_undefer.all;
 179    --           exceptional_complete_entry_body (_object._object'
 180    --             unchecked_access, current_exception, objectF => 0);
 181    --           return;
 182    --     end rPT__E14b;
 183
 184    procedure Selective_Wait
 185      (Open_Accepts       : Accept_List_Access;
 186       Select_Mode        : Select_Modes;
 187       Uninterpreted_Data : out System.Address;
 188       Index              : out Select_Index);
 189    --  Implement select statement.
 190    --  Compiler interface only. Do not call from within the RTS.
 191    --  See comments on Accept_Call.
 192    --
 193    --  source:
 194    --     select accept e1 do
 195    --           ...A...
 196    --        end e1;
 197    --        ...B...
 198    --     or accept e2;
 199    --        ...C...
 200    --     end select;
 201    --
 202    --  expansion:
 203    --     A32b : address;
 204    --     declare
 205    --        A37b : T36b;
 206    --        A37b (1) := (null_body => false, s => 1);
 207    --        A37b (2) := (null_body => true, s => 2);
 208    --        S0 : aliased T36b := accept_list'A37b;
 209    --        J1 : select_index := 0;
 210    --        procedure e1A is
 211    --        begin
 212    --           abort_undefer.all;
 213    --           ...A...
 214    --           <<L31b>>
 215    --           complete_rendezvous;
 216    --        exception
 217    --           when all others =>
 218    --              exceptional_complete_rendezvous (get_gnat_exception);
 219    --        end e1A;
 220    --     begin
 221    --        selective_wait (S0'unchecked_access, simple_mode, A32b, J1);
 222    --        case J1 is
 223    --           when 0 =>
 224    --              goto L3;
 225    --           when 1 =>
 226    --              e1A;
 227    --              goto L1;
 228    --           when 2 =>
 229    --              goto L2;
 230    --           when others =>
 231    --              goto L3;
 232    --        end case;
 233    --        <<L1>>
 234    --        ...B...
 235    --        goto L3;
 236    --        <<L2>>
 237    --        ...C...
 238    --        goto L3;
 239    --        <<L3>>
 240    --     end;
 241
 242    procedure Timed_Selective_Wait
 243      (Open_Accepts       : Accept_List_Access;
 244       Select_Mode        : Select_Modes;
 245       Uninterpreted_Data : out System.Address;
 246       Timeout            : Duration;
 247       Mode               : Delay_Modes;
 248       Index              : out Select_Index);
 249    --  Selective wait with timeout without using ATC.
 250    --  Compiler interface only. Do not call from within the RTS.
 251
 252    procedure Accept_Call
 253      (E                  : Task_Entry_Index;
 254       Uninterpreted_Data : out System.Address);
 255    --  Accept an entry call.
 256    --  Compiler interface only. Do not call from within the RTS.
 257    --
 258    --  source:
 259    --              accept E do  ...A... end E;
 260    --  expansion:
 261    --              A27b : address;
 262    --              L26b : label
 263    --              begin
 264    --                 accept_call (1, A27b);
 265    --                 ...A...
 266    --                 complete_rendezvous;
 267    --              <<L26b>>
 268    --              exception
 269    --              when all others =>
 270    --                 exceptional_complete_rendezvous (get_gnat_exception);
 271    --              end;
 272    --
 273    --  The handler for Abort_Signal (*all* others) is to handle the case when
 274    --  the acceptor is aborted between Accept_Call and the corresponding
 275    --  Complete_Rendezvous call. We need to wake up the caller in this case.
 276    --
 277    --   See also Selective_Wait
 278
 279    procedure Accept_Trivial (E : Task_Entry_Index);
 280    --  Accept an entry call that has no parameters and no body.
 281    --  Compiler interface only. Do not call from within the RTS.
 282    --  This should only be called when there is no accept body, or the accept
 283    --  body is empty.
 284    --
 285    --  source:
 286    --               accept E;
 287    --  expansion:
 288    --               accept_trivial (1);
 289    --
 290    --  The compiler is also able to recognize the following and
 291    --  translate it the same way.
 292    --
 293    --     accept E do null; end E;
 294
 295    function Task_Count (E : Task_Entry_Index) return Natural;
 296    --  Return number of tasks waiting on the entry E (of current task)
 297    --  Compiler interface only. Do not call from within the RTS.
 298
 299    function Callable (T : Task_ID) return Boolean;
 300    --  Return T'Callable
 301    --  Compiler interface. Do not call from within the RTS, except for body of
 302    --  Ada.Task_Identification.
 303
 304    type Task_Entry_Nesting_Depth is new Task_Entry_Index
 305      range 0 .. Max_Task_Entry;
 306
 307    function Task_Entry_Caller (D : Task_Entry_Nesting_Depth) return Task_ID;
 308    --  Return E'Caller. This will only work if called from within an
 309    --  accept statement that is handling E, as required by the LRM (C.7.1(14)).
 310    --  Compiler interface only. Do not call from within the RTS.
 311
 312    procedure Complete_Rendezvous;
 313    --  Called by acceptor to wake up caller
 314
 315    procedure Exceptional_Complete_Rendezvous
 316      (Ex : Ada.Exceptions.Exception_Id);
 317    --  Called by acceptor to mark the end of the current rendezvous and
 318    --  propagate an exception to the caller.
 319
 320    --  For internal use only:
 321
 322    function Task_Do_Or_Queue
 323      (Self_ID    : Task_ID;
 324       Entry_Call : Entry_Call_Link;
 325       With_Abort : Boolean) return Boolean;
 326    --  Call this only with abort deferred and holding no locks, except
 327    --  the global RTS lock when Single_Lock is True which must be owned.
 328    --  Returns False iff the call cannot be served or queued, as is the
 329    --  case if the caller is not callable; i.e., a False return value
 330    --  indicates that Tasking_Error should be raised.
 331    --  Either initiate the entry call, such that the accepting task is
 332    --  free to execute the rendezvous, queue the call on the acceptor's
 333    --  queue, or cancel the call. Conditional calls that cannot be
 334    --  accepted immediately are cancelled.
 335
 336 end System.Tasking.Rendezvous;