gcc/ada/libgnat/s-soflin.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                    S Y S T E M . S O F T _ L I N K S                     --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2024, Free Software Foundation, Inc.         --
  10 --                                                                          --
  11 -- GNAT 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 -- GNAT was originally developed  by the GNAT team at  New York University. --
  28 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  29 --                                                                          --
  30 ------------------------------------------------------------------------------
  31
  32 --  This package contains a set of subprogram access variables that access
  33 --  some low-level primitives that are different depending whether tasking is
  34 --  involved or not (e.g. the Get/Set_Jmpbuf_Address that needs to provide a
  35 --  different value for each task). To avoid dragging in the tasking runtimes
  36 --  all the time, we use a system of soft links where the links are
  37 --  initialized to non-tasking versions, and then if the tasking support is
  38 --  initialized, they are set to the real tasking versions.
  39
  40 with Ada.Exceptions;
  41 with System.Parameters;
  42 with System.Secondary_Stack;
  43 with System.Stack_Checking;
  44
  45 package System.Soft_Links is
  46    pragma Preelaborate;
  47
  48    package SST renames System.Secondary_Stack;
  49
  50    subtype EOA is Ada.Exceptions.Exception_Occurrence_Access;
  51    subtype EO is Ada.Exceptions.Exception_Occurrence;
  52
  53    function Current_Target_Exception return EO;
  54    pragma Import
  55      (Ada, Current_Target_Exception, "__gnat_current_target_exception");
  56    --  Import this subprogram from the private part of Ada.Exceptions
  57
  58    --  First we have the access subprogram types used to establish the links.
  59    --  The approach is to establish variables containing access subprogram
  60    --  values, which by default point to dummy no tasking versions of routines.
  61
  62    type No_Param_Proc     is access procedure;
  63    pragma Favor_Top_Level (No_Param_Proc);
  64    pragma Suppress_Initialization (No_Param_Proc);
  65    --  Some uninitialized objects of that type are initialized by the Binder
  66    --  so it is important that such objects are not reset to null during
  67    --  elaboration.
  68
  69    type Addr_Param_Proc   is access procedure (Addr : Address);
  70    pragma Favor_Top_Level (Addr_Param_Proc);
  71    type EO_Param_Proc     is access procedure (Excep : EO);
  72    pragma Favor_Top_Level (EO_Param_Proc);
  73
  74    type Get_Address_Call  is access function return Address;
  75    pragma Favor_Top_Level (Get_Address_Call);
  76    type Set_Address_Call  is access procedure (Addr : Address);
  77    pragma Favor_Top_Level (Set_Address_Call);
  78    type Set_Address_Call2 is access procedure
  79      (Self_ID : Address; Addr : Address);
  80    pragma Favor_Top_Level (Set_Address_Call2);
  81
  82    type Get_Integer_Call  is access function return Integer;
  83    pragma Favor_Top_Level (Get_Integer_Call);
  84    type Set_Integer_Call  is access procedure (Len : Integer);
  85    pragma Favor_Top_Level (Set_Integer_Call);
  86
  87    type Get_EOA_Call      is access function return EOA;
  88    pragma Favor_Top_Level (Get_EOA_Call);
  89    type Set_EOA_Call      is access procedure (Excep : EOA);
  90    pragma Favor_Top_Level (Set_EOA_Call);
  91    type Set_EO_Call       is access procedure (Excep : EO);
  92    pragma Favor_Top_Level (Set_EO_Call);
  93
  94    type Get_Stack_Call    is access function return SST.SS_Stack_Ptr;
  95    pragma Favor_Top_Level (Get_Stack_Call);
  96    type Set_Stack_Call    is access procedure (Stack : SST.SS_Stack_Ptr);
  97    pragma Favor_Top_Level (Set_Stack_Call);
  98
  99    type Special_EO_Call   is access
 100      procedure (Excep : EO := Current_Target_Exception);
 101    pragma Favor_Top_Level (Special_EO_Call);
 102
 103    type Timed_Delay_Call  is access
 104      procedure (Time : Duration; Mode : Integer);
 105    pragma Favor_Top_Level (Timed_Delay_Call);
 106
 107    type Get_Stack_Access_Call is access
 108      function return Stack_Checking.Stack_Access;
 109    pragma Favor_Top_Level (Get_Stack_Access_Call);
 110
 111    type Task_Name_Call is access
 112      function return String;
 113    pragma Favor_Top_Level (Task_Name_Call);
 114
 115    --  Suppress checks on all these types, since we know the corresponding
 116    --  values can never be null (the soft links are always initialized).
 117
 118    pragma Suppress (Access_Check, No_Param_Proc);
 119    pragma Suppress (Access_Check, Addr_Param_Proc);
 120    pragma Suppress (Access_Check, EO_Param_Proc);
 121    pragma Suppress (Access_Check, Get_Address_Call);
 122    pragma Suppress (Access_Check, Set_Address_Call);
 123    pragma Suppress (Access_Check, Set_Address_Call2);
 124    pragma Suppress (Access_Check, Get_Integer_Call);
 125    pragma Suppress (Access_Check, Set_Integer_Call);
 126    pragma Suppress (Access_Check, Get_EOA_Call);
 127    pragma Suppress (Access_Check, Set_EOA_Call);
 128    pragma Suppress (Access_Check, Get_Stack_Call);
 129    pragma Suppress (Access_Check, Set_Stack_Call);
 130    pragma Suppress (Access_Check, Timed_Delay_Call);
 131    pragma Suppress (Access_Check, Get_Stack_Access_Call);
 132    pragma Suppress (Access_Check, Task_Name_Call);
 133
 134    --  The following one is not related to tasking/no-tasking but to the
 135    --  traceback decorators for exceptions.
 136
 137    type Traceback_Decorator_Wrapper_Call is access
 138      function (Traceback : System.Address;
 139                Len       : Natural)
 140                return      String;
 141    pragma Favor_Top_Level (Traceback_Decorator_Wrapper_Call);
 142
 143    --  Declarations for the no tasking versions of the required routines
 144
 145    procedure Abort_Defer_NT;
 146    --  Defer task abort (non-tasking case, does nothing)
 147
 148    procedure Abort_Undefer_NT;
 149    --  Undefer task abort (non-tasking case, does nothing)
 150
 151    procedure Abort_Handler_NT;
 152    --  Handle task abort (non-tasking case, does nothing). Currently, no port
 153    --  makes use of this, but we retain the interface for possible future use.
 154
 155    function Check_Abort_Status_NT return Integer;
 156    --  Returns Boolean'Pos (True) iff abort signal should raise
 157    --  Standard'Abort_Signal.
 158
 159    procedure Task_Lock_NT;
 160    --  Lock out other tasks (non-tasking case, does nothing)
 161
 162    procedure Task_Unlock_NT;
 163    --  Release lock set by Task_Lock (non-tasking case, does nothing)
 164
 165    procedure Task_Termination_NT (Excep : EO);
 166    --  Handle task termination routines for the environment task (non-tasking
 167    --  case, does nothing).
 168
 169    procedure Adafinal_NT;
 170    --  Shuts down the runtime system (non-tasking case)
 171
 172    Abort_Defer : No_Param_Proc := Abort_Defer_NT'Access;
 173    pragma Suppress (Access_Check, Abort_Defer);
 174    --  Defer task abort (task/non-task case as appropriate)
 175
 176    Abort_Undefer : No_Param_Proc := Abort_Undefer_NT'Access;
 177    pragma Suppress (Access_Check, Abort_Undefer);
 178    --  Undefer task abort (task/non-task case as appropriate)
 179
 180    Abort_Handler : No_Param_Proc := Abort_Handler_NT'Access;
 181    --  Handle task abort (task/non-task case as appropriate)
 182
 183    Check_Abort_Status : Get_Integer_Call := Check_Abort_Status_NT'Access;
 184    --  Called when Abort_Signal is delivered to the process.  Checks to
 185    --  see if signal should result in raising Standard'Abort_Signal.
 186
 187    Lock_Task : No_Param_Proc := Task_Lock_NT'Access;
 188    --  Locks out other tasks. Preceding a section of code by Task_Lock and
 189    --  following it by Task_Unlock creates a critical region. This is used
 190    --  for ensuring that a region of non-tasking code (such as code used to
 191    --  allocate memory) is tasking safe. Note that it is valid for calls to
 192    --  Task_Lock/Task_Unlock to be nested, and this must work properly, i.e.
 193    --  only the corresponding outer level Task_Unlock will actually unlock.
 194    --  This routine also prevents against asynchronous aborts (abort is
 195    --  deferred).
 196
 197    Unlock_Task : No_Param_Proc := Task_Unlock_NT'Access;
 198    --  Releases lock previously set by call to Lock_Task. In the nested case,
 199    --  all nested locks must be released before other tasks competing for the
 200    --  tasking lock are released.
 201    --
 202    --  In the non nested case, this routine terminates the protection against
 203    --  asynchronous aborts introduced by Lock_Task (unless abort was already
 204    --  deferred before the call to Lock_Task (e.g in a protected procedures).
 205    --
 206    --  Note: the recommended protocol for using Lock_Task and Unlock_Task
 207    --  is as follows:
 208    --
 209    --    Locked_Processing : begin
 210    --       System.Soft_Links.Lock_Task.all;
 211    --       ...
 212    --       System.Soft_Links.Unlock_Task.all;
 213    --
 214    --    exception
 215    --       when others =>
 216    --          System.Soft_Links.Unlock_Task.all;
 217    --          raise;
 218    --    end Locked_Processing;
 219    --
 220    --  This ensures that the lock is not left set if an exception is raised
 221    --  explicitly or implicitly during the critical locked region.
 222
 223    Task_Termination_Handler : EO_Param_Proc := Task_Termination_NT'Access;
 224    --  Handle task termination routines (task/non-task case as appropriate)
 225
 226    Finalize_Library_Objects : No_Param_Proc;
 227    pragma Export (C, Finalize_Library_Objects,
 228                   "__gnat_finalize_library_objects");
 229    --  Will be initialized by the binder
 230
 231    Adafinal : No_Param_Proc := Adafinal_NT'Access;
 232    --  Performs the finalization of the Ada Runtime
 233
 234    function  Get_Jmpbuf_Address_NT return  Address;
 235    procedure Set_Jmpbuf_Address_NT (Addr : Address);
 236
 237    Get_Jmpbuf_Address : Get_Address_Call := Get_Jmpbuf_Address_NT'Access;
 238    Set_Jmpbuf_Address : Set_Address_Call := Set_Jmpbuf_Address_NT'Access;
 239
 240    function  Get_Sec_Stack_NT return  SST.SS_Stack_Ptr;
 241    procedure Set_Sec_Stack_NT (Stack : SST.SS_Stack_Ptr);
 242
 243    Get_Sec_Stack : Get_Stack_Call := Get_Sec_Stack_NT'Access;
 244    Set_Sec_Stack : Set_Stack_Call := Set_Sec_Stack_NT'Access;
 245
 246    function Get_Current_Excep_NT return EOA;
 247
 248    Get_Current_Excep : Get_EOA_Call := Get_Current_Excep_NT'Access;
 249
 250    function Get_Stack_Info_NT return Stack_Checking.Stack_Access;
 251
 252    Get_Stack_Info : Get_Stack_Access_Call := Get_Stack_Info_NT'Access;
 253
 254    ----------------------
 255    -- Locking Soft-Links --
 256    ----------------------
 257
 258    procedure Null_Set_Address (Addr : Address) is null;
 259
 260    --  Soft-Links are used for procedures that manipulate locks to avoid
 261    --  dragging the tasking runtime when using access-to-controlled types.
 262
 263    Initialize_RTS_Lock : Set_Address_Call := Null_Set_Address'Access;
 264    Finalize_RTS_Lock   : Set_Address_Call := Null_Set_Address'Access;
 265    Acquire_RTS_Lock    : Set_Address_Call := Null_Set_Address'Access;
 266    Release_RTS_Lock    : Set_Address_Call := Null_Set_Address'Access;
 267    --  The initialization of these variables must be static because the value
 268    --  needs to be overridden very early when the tasking runtime is dragged.
 269
 270    --------------------------
 271    -- Master_Id Soft-Links --
 272    --------------------------
 273
 274    --  Soft-Links are used for procedures that manipulate Master_Ids because
 275    --  a Master_Id must be generated for access to limited class-wide types,
 276    --  whose root may be extended with task components.
 277
 278    function Current_Master_NT return Integer;
 279    procedure Enter_Master_NT;
 280    procedure Complete_Master_NT;
 281
 282    Current_Master  : Get_Integer_Call := Current_Master_NT'Access;
 283    Enter_Master    : No_Param_Proc    := Enter_Master_NT'Access;
 284    Complete_Master : No_Param_Proc    := Complete_Master_NT'Access;
 285
 286    ----------------------
 287    -- Delay Soft-Links --
 288    ----------------------
 289
 290    --  Soft-Links are used for procedures that manipulate time to avoid
 291    --  dragging the tasking run time when using delay statements.
 292
 293    Timed_Delay : Timed_Delay_Call;
 294
 295    --------------------------
 296    -- Task Name Soft-Links --
 297    --------------------------
 298
 299    function Task_Name_NT return String;
 300
 301    Task_Name : Task_Name_Call := Task_Name_NT'Access;
 302
 303    -------------------------------------
 304    -- Exception Tracebacks Soft-Links --
 305    -------------------------------------
 306
 307    Library_Exception : EO;
 308    --  Library-level finalization routines use this common reference to store
 309    --  the first library-level exception which occurs during finalization.
 310
 311    Library_Exception_Set : Boolean := False;
 312    --  Used in conjunction with Library_Exception, set when an exception has
 313    --  been stored.
 314
 315    Traceback_Decorator_Wrapper : Traceback_Decorator_Wrapper_Call;
 316    --  Wrapper to the possible user specified traceback decorator to be
 317    --  called during automatic output of exception data.
 318
 319    --  The null value of this wrapper corresponds to the null value of the
 320    --  current actual decorator. This is ensured first by the null initial
 321    --  value of the corresponding variables, and then by Set_Trace_Decorator
 322    --  in g-exctra.adb.
 323
 324    pragma Atomic (Traceback_Decorator_Wrapper);
 325    --  Since concurrent read/write operations may occur on this variable.
 326    --  See the body of Tailored_Exception_Traceback in
 327    --  Ada.Exceptions.Exception_Data for a more detailed description of the
 328    --  potential problems.
 329
 330    procedure Save_Library_Occurrence (E : EOA);
 331    --  When invoked, this routine saves an exception occurrence into a hidden
 332    --  reference. Subsequent calls will have no effect.
 333
 334    ------------------------
 335    -- Task Specific Data --
 336    ------------------------
 337
 338    --  Here we define a single type that encapsulates the various task
 339    --  specific data. This type is used to store the necessary data into the
 340    --  Task_Control_Block or into a global variable in the non tasking case.
 341
 342    type TSD is record
 343       Pri_Stack_Info : aliased Stack_Checking.Stack_Info;
 344       --  Information on stack (Base/Limit/Size) used by System.Stack_Checking.
 345       --  If this TSD does not belong to the environment task, the Size field
 346       --  must be initialized to the tasks requested stack size before the task
 347       --  can do its first stack check.
 348
 349       Jmpbuf_Address : System.Address;
 350       --  Address of jump buffer used to store the address of the current
 351       --  longjmp/setjmp buffer for exception management. These buffers are
 352       --  threaded into a stack, and the address here is the top of the stack.
 353       --  A null address means that no exception handler is currently active.
 354
 355       Sec_Stack_Ptr : SST.SS_Stack_Ptr;
 356       --  Pointer of the allocated secondary stack
 357
 358       Current_Excep : aliased EO;
 359       --  Exception occurrence that contains the information for the current
 360       --  exception. Note that any exception in the same task destroys this
 361       --  information, so the data in this variable must be copied out before
 362       --  another exception can occur.
 363       --
 364       --  Also act as a list of the active exceptions in the case of the GCC
 365       --  exception mechanism, organized as a stack with the most recent first.
 366    end record;
 367
 368    procedure Create_TSD
 369      (New_TSD        : in out TSD;
 370       Sec_Stack      : SST.SS_Stack_Ptr;
 371       Sec_Stack_Size : System.Parameters.Size_Type);
 372    pragma Inline (Create_TSD);
 373    --  Called from s-tassta when a new thread is created to perform
 374    --  any required initialization of the TSD.
 375
 376    procedure Destroy_TSD (Old_TSD : in out TSD);
 377    pragma Inline (Destroy_TSD);
 378    --  Called from s-tassta just before a thread is destroyed to perform
 379    --  any required finalization.
 380
 381    function Get_GNAT_Exception return Ada.Exceptions.Exception_Id;
 382    pragma Inline (Get_GNAT_Exception);
 383    --  This function obtains the Exception_Id from the Exception_Occurrence
 384    --  referenced by the Current_Excep field of the task specific data, i.e.
 385    --  the call is equivalent to
 386    --  Exception_Identity (Get_Current_Exception.all)
 387
 388    --  Export the Get/Set routines for the various Task Specific Data (TSD)
 389    --  elements as callable subprograms instead of objects of access to
 390    --  subprogram types.
 391
 392    function  Get_Jmpbuf_Address_Soft return  Address;
 393    procedure Set_Jmpbuf_Address_Soft (Addr : Address);
 394    pragma Inline (Get_Jmpbuf_Address_Soft);
 395    pragma Inline (Set_Jmpbuf_Address_Soft);
 396
 397    function  Get_Sec_Stack_Soft return  SST.SS_Stack_Ptr;
 398    procedure Set_Sec_Stack_Soft (Stack : SST.SS_Stack_Ptr);
 399    pragma Inline (Get_Sec_Stack_Soft);
 400    pragma Inline (Set_Sec_Stack_Soft);
 401
 402    --  The following is a dummy record designed to mimic Communication_Block as
 403    --  defined in s-tpobop.ads:
 404
 405    --     type Communication_Block is record
 406    --        Self      : Task_Id;  --  An access type
 407    --        Enqueued  : Boolean := True;
 408    --        Cancelled : Boolean := False;
 409    --     end record;
 410
 411    --  The record is used in the construction of the predefined dispatching
 412    --  primitive _disp_asynchronous_select in order to avoid the import of
 413    --  System.Tasking.Protected_Objects.Operations. Note that this package
 414    --  is always imported in the presence of interfaces since the dispatch
 415    --  table uses entities from here.
 416
 417    type Dummy_Communication_Block is record
 418       Comp_1 : Address;  --  Address and access have the same size
 419       Comp_2 : Boolean;
 420       Comp_3 : Boolean;
 421    end record;
 422
 423 private
 424    NT_TSD : TSD;
 425    --  The task specific data for the main task when the Ada tasking run-time
 426    --  is not used. It relies on the default initialization of NT_TSD. It is
 427    --  placed here and not the body to ensure the default initialization does
 428    --  not clobber the secondary stack initialization that occurs as part of
 429    --  System.Soft_Links.Initialization.
 430 end System.Soft_Links;