1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- A D A . E X C E P T I O N S --
11 -- Copyright (C) 1992-2001 Free Software Foundation, Inc. --
13 -- This specification is derived from the Ada Reference Manual for use with --
14 -- GNAT. The copyright notice above, and the license provisions that follow --
15 -- apply solely to the contents of the part following the private keyword. --
17 -- GNAT is free software; you can redistribute it and/or modify it under --
18 -- terms of the GNU General Public License as published by the Free Soft- --
19 -- ware Foundation; either version 2, or (at your option) any later ver- --
20 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
21 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
22 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
23 -- for more details. You should have received a copy of the GNU General --
24 -- Public License distributed with GNAT; see file COPYING. If not, write --
25 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
26 -- MA 02111-1307, USA. --
28 -- As a special exception, if other files instantiate generics from this --
29 -- unit, or you link this unit with other files to produce an executable, --
30 -- this unit does not by itself cause the resulting executable to be --
31 -- covered by the GNU General Public License. This exception does not --
32 -- however invalidate any other reasons why the executable file might be --
33 -- covered by the GNU Public License. --
35 -- GNAT was originally developed by the GNAT team at New York University. --
36 -- It is now maintained by Ada Core Technologies Inc (http://www.gnat.com). --
38 ------------------------------------------------------------------------------
41 -- We must turn polling off for this unit, because otherwise we get
42 -- elaboration circularities with ourself.
45 with System
.Standard_Library
;
47 package Ada
.Exceptions
is
49 type Exception_Id
is private;
50 Null_Id
: constant Exception_Id
;
52 type Exception_Occurrence
is limited private;
53 type Exception_Occurrence_Access
is access all Exception_Occurrence
;
55 Null_Occurrence
: constant Exception_Occurrence
;
57 function Exception_Name
(X
: Exception_Occurrence
) return String;
58 -- Same as Exception_Name (Exception_Identity (X))
60 function Exception_Name
(Id
: Exception_Id
) return String;
62 procedure Raise_Exception
(E
: Exception_Id
; Message
: String := "");
63 -- Note: it would be really nice to give a pragma No_Return for this
64 -- procedure, but it would be wrong, since Raise_Exception does return
65 -- if given the null exception. However we do special case the name in
66 -- the test in the compiler for issuing a warning for a missing return
67 -- after this call. Program_Error seems reasonable enough in such a case.
68 -- See also the routine Raise_Exception_Always in the private part.
70 function Exception_Message
(X
: Exception_Occurrence
) return String;
72 procedure Reraise_Occurrence
(X
: Exception_Occurrence
);
73 -- Note: it would be really nice to give a pragma No_Return for this
74 -- procedure, but it would be wrong, since Reraise_Occurrence does return
75 -- if the argument is the null exception occurrence. See also procedure
76 -- Reraise_Occurrence_Always in the private part of this package.
78 function Exception_Identity
(X
: Exception_Occurrence
) return Exception_Id
;
80 function Exception_Information
(X
: Exception_Occurrence
) return String;
81 -- The format of the exception information is as follows:
83 -- exception name (as in Exception_Name)
84 -- message (or a null line if no message)
86 -- 0xyyyyyyyy 0xyyyyyyyy ...
88 -- The lines are separated by an ASCII.CR/ASCII.LF sequence.
89 -- The nnnn is the partition Id given as decimal digits.
90 -- The 0x... line represents traceback program counter locations,
91 -- in order with the first one being the exception location.
93 -- Note on ordering: the compiler uses the Save_Occurrence procedure, but
94 -- not the function from Rtsfind, so it is important that the procedure
95 -- come first, since Rtsfind finds the first matching entity.
97 procedure Save_Occurrence
98 (Target
: out Exception_Occurrence
;
99 Source
: Exception_Occurrence
);
101 function Save_Occurrence
102 (Source
: Exception_Occurrence
)
103 return Exception_Occurrence_Access
;
106 package SSL
renames System
.Standard_Library
;
108 subtype EOA
is Exception_Occurrence_Access
;
110 Exception_Msg_Max_Length
: constant := 200;
116 subtype Code_Loc
is System
.Address
;
117 -- Code location used in building exception tables and for call
118 -- addresses when propagating an exception (also traceback table)
119 -- Values of this type are created by using Label'Address or
120 -- extracted from machine states using Get_Code_Loc.
122 Null_Loc
: constant Code_Loc
:= System
.Null_Address
;
123 -- Null code location, used to flag outer level frame
125 type Exception_Id
is new SSL
.Exception_Data_Ptr
;
127 function EId_To_String
(X
: Exception_Id
) return String;
128 function String_To_EId
(S
: String) return Exception_Id
;
129 pragma Stream_Convert
(Exception_Id
, String_To_EId
, EId_To_String
);
130 -- Functions for implementing Exception_Id stream attributes
132 Null_Id
: constant Exception_Id
:= null;
134 -------------------------
135 -- Private Subprograms --
136 -------------------------
138 function Current_Target_Exception
return Exception_Occurrence
;
140 (Ada
, Current_Target_Exception
,
141 "__gnat_current_target_exception");
142 -- This routine should return the current raised exception on targets
143 -- which have built-in exception handling such as the Java Virtual
144 -- Machine. For other targets this routine is simply ignored. Currently,
145 -- only JGNAT uses this. See 4jexcept.ads for details. The pragma Export
146 -- allows this routine to be accessed elsewhere in the run-time, even
147 -- though it is in the private part of this package (it is not allowed
148 -- to be in the visible part, since this is set by the reference manual).
150 function Exception_Name_Simple
(X
: Exception_Occurrence
) return String;
151 -- Like Exception_Name, but returns the simple non-qualified name of
152 -- the exception. This is used to implement the Exception_Name function
153 -- in Current_Exceptions (the DEC compatible unit). It is called from
154 -- the compiler generated code (using Rtsfind, which does not respect
155 -- the private barrier, so we can place this function in the private
156 -- part where the compiler can find it, but the spec is unchanged.)
158 procedure Raise_Exception_Always
(E
: Exception_Id
; Message
: String := "");
159 pragma No_Return
(Raise_Exception_Always
);
160 pragma Export
(Ada
, Raise_Exception_Always
, "__gnat_raise_exception");
161 -- This differs from Raise_Exception only in that the caller has determined
162 -- that for sure the parameter E is not null, and that therefore the call
163 -- to this procedure cannot return. The expander converts Raise_Exception
164 -- calls to Raise_Exception_Always if it can determine this is the case.
165 -- The Export allows this routine to be accessed from Pure units.
167 procedure Raise_No_Msg
(E
: Exception_Id
);
168 pragma No_Return
(Raise_No_Msg
);
169 -- Raises an exception with no message with given exception id value.
170 -- Abort is deferred before the raise call.
172 procedure Raise_From_Signal_Handler
174 M
: SSL
.Big_String_Ptr
);
176 (Ada
, Raise_From_Signal_Handler
,
177 "ada__exceptions__raise_from_signal_handler");
178 pragma No_Return
(Raise_From_Signal_Handler
);
179 -- This routine is used to raise an exception from a signal handler.
180 -- The signal handler has already stored the machine state (i.e. the
181 -- state that corresponds to the location at which the signal was
182 -- raised). E is the Exception_Id specifying what exception is being
183 -- raised, and M is a pointer to a null-terminated string which is the
184 -- message to be raised. Note that this routine never returns, so it is
185 -- permissible to simply jump to this routine, rather than call it. This
186 -- may be appropriate for systems where the right way to get out of a
187 -- signal handler is to alter the PC value in the machine state or in
188 -- some other way ask the operating system to return here rather than
189 -- to the original location.
191 procedure Raise_With_C_Msg
193 M
: SSL
.Big_String_Ptr
);
194 pragma Export
(Ada
, Raise_With_C_Msg
, "ada__exceptions__raise_with_c_msg");
195 pragma No_Return
(Raise_With_C_Msg
);
196 -- Raises an exception with with given exception id value and message.
197 -- M is a null terminated string with the message to be raised. Abort
198 -- is deferred before the raise call.
200 procedure Reraise_Occurrence_Always
(X
: Exception_Occurrence
);
201 pragma No_Return
(Reraise_Occurrence_Always
);
202 -- This differs from Raise_Occurrence only in that the caller guarantees
203 -- that for sure the parameter X is not the null occurrence, and that
204 -- therefore this procedure cannot return. The expander uses this routine
205 -- in the translation of a raise statement with no parameter (reraise).
207 procedure Reraise_Occurrence_No_Defer
(X
: Exception_Occurrence
);
208 pragma No_Return
(Reraise_Occurrence_No_Defer
);
209 -- Exactly like Reraise_Occurrence, except that abort is not deferred
210 -- before the call and the parameter X is known not to be the null
211 -- occurrence. This is used in generated code when it is known
212 -- that abort is already deferred.
214 procedure SDP_Table_Build
215 (SDP_Addresses
: System
.Address
;
217 Elab_Addresses
: System
.Address
;
218 Elab_Addr_Count
: Natural);
219 pragma Export
(C
, SDP_Table_Build
, "__gnat_SDP_Table_Build");
220 -- This is the routine that is called to build and sort the list of
221 -- subprogram descriptor pointers. In the normal case it is called
222 -- once at the start of execution, but it can also be called as part
223 -- of the explicit initialization routine (adainit) when there is no
224 -- Ada main program. In particular, in the case where multiple Ada
225 -- libraries are present, this routine can be called more than once
226 -- for each library, in which case it augments the previously set
227 -- table with the new entries specified by the parameters.
229 -- SDP_Addresses Address of the start of the list of addresses of
230 -- __gnat_unit_name__SDP values constructed for each
231 -- unit, (see System.Exceptions).
233 -- SDP_Count Number of entries in SDP_Addresses
235 -- Elab_Addresses Address of the start of a list of addresses of
236 -- generated Ada elaboration routines, as well as
237 -- one extra entry for the generated main program.
238 -- These are used to generate the dummy SDP's that
239 -- mark the outer scope.
241 -- Elab_Addr_Count Number of entries in Elab_Addresses
243 procedure Break_Start
;
244 pragma Export
(C
, Break_Start
, "__gnat_break_start");
245 -- This is a dummy procedure that is called at the start of execution.
246 -- Its sole purpose is to provide a well defined point for the placement
247 -- of a main program breakpoint. We put the routine in Ada.Exceptions so
248 -- that the standard mechanism of always stepping up from breakpoints
249 -- within Ada.Exceptions leaves us sitting in the main program.
251 -----------------------
252 -- Polling Interface --
253 -----------------------
255 -- The GNAT compiler has an option to generate polling calls to the Poll
256 -- routine in this package. Specifying the -gnatP option for a compilation
257 -- causes a call to Ada.Exceptions.Poll to be generated on every subprogram
258 -- entry and on every iteration of a loop, thus avoiding the possibility of
259 -- a case of unbounded time between calls.
261 -- This polling interface may be used for instrumentation or debugging
262 -- purposes (e.g. implementing watchpoints in software or in the debugger).
264 -- In the GNAT technology itself, this interface is used to implement
265 -- immediate aynschronous transfer of control and immediate abort on
266 -- targets which do not provide for one thread interrupting another.
268 -- Note: this used to be in a separate unit called System.Poll, but that
269 -- caused horrible circular elaboration problems between System.Poll and
270 -- Ada.Exceptions. One way of solving such circularities is unification!
273 -- Check for asynchronous abort. Note that we do not inline the body.
274 -- This makes the interface more useful for debugging purposes.
276 --------------------------
277 -- Exception_Occurrence --
278 --------------------------
280 Max_Tracebacks
: constant := 50;
281 -- Maximum number of trace backs stored in exception occurrence
283 type Tracebacks_Array
is array (1 .. Max_Tracebacks
) of Code_Loc
;
284 -- Traceback array stored in exception occurrence
286 type Exception_Occurrence
is record
288 -- Exception_Identity for this exception occurrence
289 -- WARNING System.System.Finalization_Implementation.Finalize_List
290 -- relies on the fact that this field is always first in the exception
293 Msg_Length
: Natural := 0;
294 -- Length of message (zero = no message)
296 Msg
: String (1 .. Exception_Msg_Max_Length
);
297 -- Characters of message
299 Cleanup_Flag
: Boolean;
300 -- The cleanup flag is normally False, it is set True for an exception
301 -- occurrence passed to a cleanup routine, and will still be set True
302 -- when the cleanup routine does a Reraise_Occurrence call using this
303 -- exception occurrence. This is used to avoid recording a bogus trace
304 -- back entry from this reraise call.
306 Exception_Raised
: Boolean := False;
307 -- Set to true to indicate that this exception occurrence has actually
308 -- been raised. When an exception occurrence is first created, this is
309 -- set to False, then when it is processed by Raise_Current_Exception,
310 -- it is set to True. If Raise_Current_Exception is used to raise an
311 -- exception for which this flag is already True, then it knows that
312 -- it is dealing with the reraise case (which is useful to distinguish
313 -- for exception tracing purposes).
316 -- Partition_Id for partition raising exception
318 Num_Tracebacks
: Natural range 0 .. Max_Tracebacks
:= 0;
319 -- Number of traceback entries stored
321 Tracebacks
: Tracebacks_Array
;
322 -- Stored tracebacks (in Tracebacks (1 .. Num_Tracebacks))
325 function "=" (Left
, Right
: Exception_Occurrence
) return Boolean
327 -- Don't allow comparison on exception occurrences, we should not need
328 -- this, and it would not work right, because of the Msg and Tracebacks
329 -- fields which have unused entries not copied by Save_Occurrence.
331 function EO_To_String
(X
: Exception_Occurrence
) return String;
332 function String_To_EO
(S
: String) return Exception_Occurrence
;
333 pragma Stream_Convert
(Exception_Occurrence
, String_To_EO
, EO_To_String
);
334 -- Functions for implementing Exception_Occurrence stream attributes
336 Null_Occurrence
: constant Exception_Occurrence
:= (
339 Msg
=> (others => ' '),
340 Cleanup_Flag
=> False,
341 Exception_Raised
=> False,
344 Tracebacks
=> (others => Null_Loc
));