gcc/ada/s-taasde.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 . A S Y N C _ D E L A Y S          --
   6 --                                                                          --
   7 --                                  S p e c                                 --
   8 --                                                                          --
   9 --                             $Revision: 1.1 $
  10 --                                                                          --
  11 --           Copyright (C) 1998-1999 Ada Core Technologies, 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. in cooperation with Florida --
  33 -- State University (http://www.gnat.com).                                  --
  34 --                                                                          --
  35 ------------------------------------------------------------------------------
  36
  37 --  This package contains the procedures to implements timeouts (delays) on
  38 --  asynchronous select statements.
  39
  40 --  Note: the compiler generates direct calls to this interface, via Rtsfind.
  41 --  Any changes to this interface may require corresponding compiler changes.
  42
  43 package System.Tasking.Async_Delays is
  44
  45    --  Suppose the following source code is given:
  46
  47    --  select delay When;
  48    --     ...continuation for timeout case...
  49    --  then abort
  50    --     ...abortable part...
  51    --  end select;
  52
  53    --  The compiler should expand this to the following:
  54
  55    --  declare
  56    --     DB : aliased Delay_Block;
  57    --  begin
  58    --     if System.Tasking.Async_Delays.Enqueue_Duration
  59    --       (When, DB'Unchecked_Access)
  60    --     then
  61    --        begin
  62    --           A101b : declare
  63    --              procedure _clean is
  64    --              begin
  65    --                 System.Tasking.Async_Delays.Cancel_Async_Delay
  66    --                   (DB'Unchecked_Access);
  67    --                 return;
  68    --              end _clean;
  69    --           begin
  70    --              abort_undefer.all;
  71    --              ...abortable part...
  72    --           exception
  73    --              when all others =>
  74    --                 declare
  75    --                    E105b : exception_occurrence;
  76    --                 begin
  77    --                    save_occurrence (E105b, get_current_excep.all.all);
  78    --                    _clean;
  79    --                    reraise_occurrence_no_defer (E105b);
  80    --                 end;
  81    --           at end
  82    --              _clean;
  83    --           end A101b;
  84    --        exception
  85    --           when _abort_signal =>
  86    --              abort_undefer.all;
  87    --        end;
  88    --     end if;
  89    --
  90    --     if Timed_Out (DB'Unchecked_Access) then
  91    --        ...continuation for timeout case...
  92    --     end if;
  93    --  end;
  94
  95    -----------------
  96    -- Delay_Block --
  97    -----------------
  98
  99    type Delay_Block is limited private;
 100    type Delay_Block_Access is access all Delay_Block;
 101
 102    function Enqueue_Duration
 103      (T : in Duration;
 104       D : Delay_Block_Access) return Boolean;
 105    --  Enqueue the specified relative delay. Returns True if the delay has
 106    --  been enqueued, False if it has already expired.
 107    --  If the delay has been enqueued, abortion is deferred.
 108
 109    procedure Cancel_Async_Delay (D : Delay_Block_Access);
 110    --  Cancel the specified asynchronous delay
 111
 112    function Timed_Out (D : Delay_Block_Access) return Boolean;
 113    pragma Inline (Timed_Out);
 114    --  Return True if the delay specified in D has timed out
 115
 116    --  There are child units for delays on Ada.Calendar.Time and
 117    --  Ada.Real_Time.Time, so that an application will not need to link in
 118    --  features that is not using.
 119
 120 private
 121
 122    type Delay_Block is record
 123       Self_Id     : Task_ID;
 124       --  ID of the calling task
 125
 126       Level       : ATC_Level_Base;
 127       --  Normally Level is the ATC nesting level of the
 128       --  async. select statement to which this delay belongs, but
 129       --  after a call has been dequeued we set it to
 130       --  ATC_Level_Infinity so that the Cancel operation can
 131       --  detect repeated calls, and act idempotently.
 132
 133       Resume_Time : Duration;
 134       --  The absolute wake up time, represented as Duration
 135
 136       Timed_Out   : Boolean := False;
 137       --  Set to true if the delay has timed out
 138
 139       Succ, Pred  : Delay_Block_Access;
 140       --  A double linked list
 141    end record;
 142
 143    --  The above "overlaying" of Self_ID and Level to hold other
 144    --  data that has a non-overlapping lifetime is an unabashed
 145    --  hack to save memory.
 146
 147    procedure Time_Enqueue
 148      (T : Duration;
 149       D : Delay_Block_Access);
 150    pragma Inline (Time_Enqueue);
 151    --  Used by the child units to enqueue delays on the timer queue
 152    --  implemented in the body of this package.
 153
 154 end System.Tasking.Async_Delays;