File : s-soflin-xi.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-2015, 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 -- --
19 -- --
20 -- --
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 -- This is a Ravenscar bare board version of this package. Tasking versions
41 -- of the primitives are always used.
42
43 with Ada.Exceptions;
44
45 package System.Soft_Links is
46 pragma Preelaborate;
47
48 subtype EOA is Ada.Exceptions.Exception_Occurrence_Access;
49 subtype EO is Ada.Exceptions.Exception_Occurrence;
50
51 -- First we have the access subprogram types used to establish the links.
52 -- The approach is to establish variables containing access subprogram
53 -- values, which by default point to dummy no tasking versions of routines.
54
55 type No_Param_Proc is access procedure;
56 pragma Suppress_Initialization (No_Param_Proc);
57 type EO_Param_Proc is access procedure (Excep : EO);
58 pragma Favor_Top_Level (EO_Param_Proc);
59
60 type Get_EOA_Call is access function return EOA;
61
62 -- Suppress checks on all these types, since we know the corrresponding
63 -- values can never be null (the soft links are always initialized).
64
65 pragma Suppress (Access_Check, No_Param_Proc);
66 pragma Suppress (Access_Check, EO_Param_Proc);
67 pragma Suppress (Access_Check, Get_EOA_Call);
68
69 -- The following one is not related to tasking/no-tasking but to the
70 -- traceback decorators for exceptions.
71
72 type Traceback_Decorator_Wrapper_Call is access
73 function (Traceback : System.Address; Len : Natural) return String;
74 pragma Favor_Top_Level (Traceback_Decorator_Wrapper_Call);
75
76 procedure Abort_Defer_Raven is null;
77 -- Defer task abort (Ravenscar case, does nothing)
78
79 procedure Abort_Undefer_Raven is null;
80 -- Undefer task abort (Ravenscar case, does nothing)
81
82 procedure Task_Lock_Soft;
83 -- Lock out other tasks
84
85 procedure Task_Unlock_Soft;
86 -- Release lock set by Task_Lock
87
88 Lock_Task : No_Param_Proc := Task_Lock_Soft'Access;
89 -- Locks out other tasks. Preceding a section of code by Task_Lock and
90 -- following it by Task_Unlock creates a critical region. This is used
91 -- for ensuring that a region of non-tasking code (such as code used to
92 -- allocate memory) is tasking safe. Note that it is valid for calls to
93 -- Task_Lock/Task_Unlock to be nested, and this must work properly, i.e.
94 -- only the corresponding outer level Task_Unlock will actually unlock.
95
96 Unlock_Task : No_Param_Proc := Task_Unlock_Soft'Access;
97 -- Releases lock previously set by call to Lock_Task. In the nested case,
98 -- all nested locks must be released before other tasks competing for the
99 -- tasking lock are released.
100 --
101 -- Note: the recommended protocol for using Lock_Task and Unlock_Task
102 -- is as follows:
103 --
104 -- Locked_Processing : begin
105 -- System.Soft_Links.Lock_Task.all;
106 -- ...
107 -- System.Soft_Links.Unlock_Task.all;
108 --
109 -- exception
110 -- when others =>
111 -- System.Soft_Links.Unlock_Task.all;
112 -- raise;
113 -- end Locked_Processing;
114 --
115 -- This ensures that the lock is not left set if an exception is raised
116 -- explicitly or implicitly during the critical locked region.
117
118 procedure Adafinal_Soft;
119 -- Programs do not terminate in Ravenscar
120
121 Adafinal : No_Param_Proc := Adafinal_Soft'Access;
122 -- Performs the finalization of the Ada Runtime
123
124 Abort_Defer : constant No_Param_Proc := Abort_Defer_Raven'Access;
125 pragma Suppress (Access_Check, Abort_Defer);
126 -- Defer task abort (task/non-task case as appropriate)
127
128 Abort_Undefer : constant No_Param_Proc := Abort_Undefer_Raven'Access;
129 pragma Suppress (Access_Check, Abort_Undefer);
130 -- Undefer task abort (task/non-task case as appropriate)
131
132 -- Declarations for the no tasking versions of the required routines
133
134 function Get_Current_Excep_Soft return EOA;
135 pragma Inline (Get_Current_Excep_Soft);
136
137 Get_Current_Excep : constant Get_EOA_Call := Get_Current_Excep_Soft'Access;
138
139 function Get_GNAT_Exception return Ada.Exceptions.Exception_Id;
140 pragma Inline (Get_GNAT_Exception);
141 -- This function obtains the Exception_Id from the Exception_Occurrence
142 -- referenced by the Current_Excep field of the task specific data, i.e.
143 -- the call is equivalent to:
144 -- Exception_Identity (Get_Current_Exception.all)
145
146 procedure Task_Termination_Soft (Except : EO);
147 -- Handle task termination routines for the environment task (non-tasking
148 -- case, does nothing).
149
150 Task_Termination_Handler : EO_Param_Proc := Task_Termination_Soft'Access;
151 -- Handle task termination routines (task/non-task case as appropriate)
152
153 -------------------------------------
154 -- Exception Tracebacks Soft-Links --
155 -------------------------------------
156
157 Library_Exception : EO;
158 -- Library-level finalization routines use this common reference to store
159 -- the first library-level exception which occurs during finalization.
160
161 Library_Exception_Set : Boolean := False;
162 -- Used in conjunction with Library_Exception, set when an exception has
163 -- been stored.
164
165 Traceback_Decorator_Wrapper : Traceback_Decorator_Wrapper_Call;
166 -- Wrapper to the possible user specified traceback decorator to be
167 -- called during automatic output of exception data.
168 --
169 -- The null value of this wrapper corresponds to the null value of the
170 -- current actual decorator. This is ensured first by the null initial
171 -- value of the corresponding variables, and then by Set_Trace_Decorator
172 -- in g-exctra.adb.
173
174 pragma Atomic (Traceback_Decorator_Wrapper);
175 -- Since concurrent read/write operations may occur on this variable. See
176 -- the body of Tailored_Exception_Traceback in Ada.Exceptions for a more
177 -- detailed description of the potential problems.
178
179 end System.Soft_Links;