blob: c1b93e0b4f2c1a353d5d58317a1c790ec15e8b77 [file] [log] [blame]
------------------------------------------------------------------------------
-- --
-- GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS --
-- --
-- S Y S T E M . T A S K I N G . A S Y N C _ D E L A Y S --
-- --
-- S p e c --
-- --
-- Copyright (C) 1998-2021, 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 the procedures to implements timeouts (delays) for
-- asynchronous select statements.
-- Note: the compiler generates direct calls to this interface, via Rtsfind.
-- Any changes to this interface may require corresponding compiler changes.
package System.Tasking.Async_Delays is
-- Suppose the following source code is given:
-- select delay When;
-- ...continuation for timeout case...
-- then abort
-- ...abortable part...
-- end select;
-- The compiler should expand this to the following:
-- declare
-- DB : aliased Delay_Block;
-- begin
-- if System.Tasking.Async_Delays.Enqueue_Duration
-- (When, DB'Unchecked_Access)
-- then
-- begin
-- A101b : declare
-- procedure _clean is
-- begin
-- System.Tasking.Async_Delays.Cancel_Async_Delay
-- (DB'Unchecked_Access);
-- return;
-- end _clean;
-- begin
-- abort_undefer.all;
-- ...abortable part...
-- exception
-- when all others =>
-- declare
-- E105b : exception_occurrence;
-- begin
-- save_occurrence (E105b, get_current_excep.all.all);
-- _clean;
-- reraise_occurrence_no_defer (E105b);
-- end;
-- at end
-- _clean;
-- end A101b;
-- exception
-- when _abort_signal =>
-- abort_undefer.all;
-- end;
-- end if;
-- if Timed_Out (DB'Unchecked_Access) then
-- ...continuation for timeout case...
-- end if;
-- end;
-----------------
-- Delay_Block --
-----------------
type Delay_Block is limited private;
type Delay_Block_Access is access all Delay_Block;
function Enqueue_Duration
(T : Duration;
D : Delay_Block_Access) return Boolean;
-- Enqueue the specified relative delay. Returns True if the delay has
-- been enqueued, False if it has already expired. If the delay has been
-- enqueued, abort is deferred.
procedure Cancel_Async_Delay (D : Delay_Block_Access);
-- Cancel the specified asynchronous delay
function Timed_Out (D : Delay_Block_Access) return Boolean;
pragma Inline (Timed_Out);
-- Return True if the delay specified in D has timed out
-- There are child units for delays on Ada.Calendar.Time/Ada.Real_Time.Time
-- so that an application need not link in features that it is not using.
private
type Delay_Block is limited record
Self_Id : Task_Id;
-- ID of the calling task
Level : ATC_Level_Base;
-- Normally Level is the ATC nesting level of the asynchronous select
-- statement to which this delay belongs, but after a call has been
-- dequeued we set it to Level_No_Pending_Abort so that the Cancel
-- operation can detect repeated calls, and act idempotently.
Resume_Time : Duration;
-- The absolute wake up time, represented as Duration
Timed_Out : Boolean := False;
-- Set to true if the delay has timed out
Succ, Pred : Delay_Block_Access;
-- A double linked list
end record;
-- The above "overlaying" of Self_Id and Level to hold other data that has
-- a non-overlapping lifetime is an unabashed hack to save memory.
procedure Time_Enqueue
(T : Duration;
D : Delay_Block_Access);
pragma Inline (Time_Enqueue);
-- Used by the child units to enqueue delays on the timer queue implemented
-- in the body of this package. T denotes a point in time as the duration
-- elapsed since the epoch of the Ada real-time clock.
end System.Tasking.Async_Delays;