1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- A D A . E X C E P T I O N S --
9 -- Copyright (C) 1992-2007, Free Software Foundation, Inc. --
11 -- This specification is derived from the Ada Reference Manual for use with --
12 -- GNAT. The copyright notice above, and the license provisions that follow --
13 -- apply solely to the contents of the part following the private keyword. --
15 -- GNAT is free software; you can redistribute it and/or modify it under --
16 -- terms of the GNU General Public License as published by the Free Soft- --
17 -- ware Foundation; either version 2, or (at your option) any later ver- --
18 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
19 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
20 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
21 -- for more details. You should have received a copy of the GNU General --
22 -- Public License distributed with GNAT; see file COPYING. If not, write --
23 -- to the Free Software Foundation, 51 Franklin Street, Fifth Floor, --
24 -- Boston, MA 02110-1301, USA. --
26 -- As a special exception, if other files instantiate generics from this --
27 -- unit, or you link this unit with other files to produce an executable, --
28 -- this unit does not by itself cause the resulting executable to be --
29 -- covered by the GNU General Public License. This exception does not --
30 -- however invalidate any other reasons why the executable file might be --
31 -- covered by the GNU Public License. --
33 -- GNAT was originally developed by the GNAT team at New York University. --
34 -- Extensive contributions were provided by Ada Core Technologies Inc. --
36 ------------------------------------------------------------------------------
38 -- This version of Ada.Exceptions is a full Ada 95 version. It omits Ada 2005
39 -- features such as the additional definitions of Exception_Name returning
40 -- Wide_[Wide_]String.
42 -- It is used for building the compiler and the basic tools, since these
43 -- builds may be done with bootstrap compilers that cannot handle these
44 -- additions. The full version of Ada.Exceptions can be found in the files
45 -- a-except-2005.ads/adb, and is used for all other builds where full Ada
46 -- 2005 functionality is required. in particular, it is used for building
47 -- run times on all targets.
50 -- We must turn polling off for this unit, because otherwise we get
51 -- elaboration circularities with ourself.
53 pragma Warnings
(Off
);
58 with System
.Parameters
;
59 with System
.Standard_Library
;
60 with System
.Traceback_Entries
;
62 package Ada
.Exceptions
is
63 pragma Warnings
(Off
);
64 pragma Preelaborate_05
;
66 -- We make this preelaborable in Ada 2005 mode. If we did not do this, then
67 -- run time units used by the compiler (e.g. s-soflin.ads) would run
68 -- into trouble. Conformance is not an issue, since this version is used
69 -- only by the compiler.
71 type Exception_Id
is private;
73 Null_Id
: constant Exception_Id
;
75 type Exception_Occurrence
is limited private;
77 type Exception_Occurrence_Access
is access all Exception_Occurrence
;
79 Null_Occurrence
: constant Exception_Occurrence
;
81 function Exception_Name
(X
: Exception_Occurrence
) return String;
82 -- Same as Exception_Name (Exception_Identity (X))
84 function Exception_Name
(Id
: Exception_Id
) return String;
86 procedure Raise_Exception
(E
: Exception_Id
; Message
: String := "");
87 -- Note: it would be really nice to give a pragma No_Return for this
88 -- procedure, but it would be wrong, since Raise_Exception does return if
89 -- given the null exception in Ada 95 mode. However we do special case the
90 -- name in the test in the compiler for issuing a warning for a missing
91 -- return after this call. Program_Error seems reasonable enough in such a
92 -- case. See also the routine Raise_Exception_Always in the private part.
94 function Exception_Message
(X
: Exception_Occurrence
) return String;
96 procedure Reraise_Occurrence
(X
: Exception_Occurrence
);
97 -- Note: it would be really nice to give a pragma No_Return for this
98 -- procedure, but it would be wrong, since Reraise_Occurrence does return
99 -- if the argument is the null exception occurrence. See also procedure
100 -- Reraise_Occurrence_Always in the private part of this package.
102 function Exception_Identity
(X
: Exception_Occurrence
) return Exception_Id
;
104 function Exception_Information
(X
: Exception_Occurrence
) return String;
105 -- The format of the exception information is as follows:
107 -- exception name (as in Exception_Name)
108 -- message (or a null line if no message)
110 -- 0xyyyyyyyy 0xyyyyyyyy ...
112 -- The lines are separated by a ASCII.LF character
113 -- The nnnn is the partition Id given as decimal digits.
114 -- The 0x... line represents traceback program counter locations,
115 -- in order with the first one being the exception location.
117 -- Note on ordering: the compiler uses the Save_Occurrence procedure, but
118 -- not the function from Rtsfind, so it is important that the procedure
119 -- come first, since Rtsfind finds the first matching entity.
121 procedure Save_Occurrence
122 (Target
: out Exception_Occurrence
;
123 Source
: Exception_Occurrence
);
125 function Save_Occurrence
126 (Source
: Exception_Occurrence
)
127 return Exception_Occurrence_Access
;
130 package SSL
renames System
.Standard_Library
;
131 package SP
renames System
.Parameters
;
133 subtype EOA
is Exception_Occurrence_Access
;
135 Exception_Msg_Max_Length
: constant := SP
.Default_Exception_Msg_Max_Length
;
141 subtype Code_Loc
is System
.Address
;
142 -- Code location used in building exception tables and for call addresses
143 -- when propagating an exception. Values of this type are created by using
144 -- Label'Address or extracted from machine states using Get_Code_Loc.
146 Null_Loc
: constant Code_Loc
:= System
.Null_Address
;
147 -- Null code location, used to flag outer level frame
149 type Exception_Id
is new SSL
.Exception_Data_Ptr
;
151 function EId_To_String
(X
: Exception_Id
) return String;
152 function String_To_EId
(S
: String) return Exception_Id
;
153 pragma Stream_Convert
(Exception_Id
, String_To_EId
, EId_To_String
);
154 -- Functions for implementing Exception_Id stream attributes
156 Null_Id
: constant Exception_Id
:= null;
158 -------------------------
159 -- Private Subprograms --
160 -------------------------
162 function Current_Target_Exception
return Exception_Occurrence
;
164 (Ada
, Current_Target_Exception
,
165 "__gnat_current_target_exception");
166 -- This routine should return the current raised exception on targets
167 -- which have built-in exception handling such as the Java Virtual
168 -- Machine. For other targets this routine is simply ignored. Currently,
169 -- only JGNAT uses this. See 4jexcept.ads for details. The pragma Export
170 -- allows this routine to be accessed elsewhere in the run-time, even
171 -- though it is in the private part of this package (it is not allowed
172 -- to be in the visible part, since this is set by the reference manual).
174 function Exception_Name_Simple
(X
: Exception_Occurrence
) return String;
175 -- Like Exception_Name, but returns the simple non-qualified name of the
176 -- exception. This is used to implement the Exception_Name function in
177 -- Current_Exceptions (the DEC compatible unit). It is called from the
178 -- compiler generated code (using Rtsfind, which does not respect the
179 -- private barrier, so we can place this function in the private part
180 -- where the compiler can find it, but the spec is unchanged.)
182 procedure Raise_Exception_Always
(E
: Exception_Id
; Message
: String := "");
183 pragma No_Return
(Raise_Exception_Always
);
184 pragma Export
(Ada
, Raise_Exception_Always
, "__gnat_raise_exception");
185 -- This differs from Raise_Exception only in that the caller has determined
186 -- that for sure the parameter E is not null, and that therefore the call
187 -- to this procedure cannot return. The expander converts Raise_Exception
188 -- calls to Raise_Exception_Always if it can determine this is the case.
189 -- The Export allows this routine to be accessed from Pure units.
191 procedure Raise_From_Signal_Handler
195 (Ada
, Raise_From_Signal_Handler
,
196 "ada__exceptions__raise_from_signal_handler");
197 pragma No_Return
(Raise_From_Signal_Handler
);
198 -- This routine is used to raise an exception from a signal handler. The
199 -- signal handler has already stored the machine state (i.e. the state that
200 -- corresponds to the location at which the signal was raised). E is the
201 -- Exception_Id specifying what exception is being raised, and M is a
202 -- pointer to a null-terminated string which is the message to be raised.
203 -- Note that this routine never returns, so it is permissible to simply
204 -- jump to this routine, rather than call it. This may be appropriate for
205 -- systems where the right way to get out of signal handler is to alter the
206 -- PC value in the machine state or in some other way ask the operating
207 -- system to return here rather than to the original location.
209 procedure Raise_From_Controlled_Operation
210 (X
: Ada
.Exceptions
.Exception_Occurrence
);
211 pragma No_Return
(Raise_From_Controlled_Operation
);
212 -- Raise Program_Error, proviving information about X (an exception
213 -- raised during a controlled operation) in the exception message.
215 procedure Reraise_Occurrence_Always
(X
: Exception_Occurrence
);
216 pragma No_Return
(Reraise_Occurrence_Always
);
217 -- This differs from Raise_Occurrence only in that the caller guarantees
218 -- that for sure the parameter X is not the null occurrence, and that
219 -- therefore this procedure cannot return. The expander uses this routine
220 -- in the translation of a raise statement with no parameter (reraise).
222 procedure Reraise_Occurrence_No_Defer
(X
: Exception_Occurrence
);
223 pragma No_Return
(Reraise_Occurrence_No_Defer
);
224 -- Exactly like Reraise_Occurrence, except that abort is not deferred
225 -- before the call and the parameter X is known not to be the null
226 -- occurrence. This is used in generated code when it is known that
227 -- abort is already deferred.
229 -----------------------
230 -- Polling Interface --
231 -----------------------
233 -- The GNAT compiler has an option to generate polling calls to the Poll
234 -- routine in this package. Specifying the -gnatP option for a compilation
235 -- causes a call to Ada.Exceptions.Poll to be generated on every subprogram
236 -- entry and on every iteration of a loop, thus avoiding the possibility of
237 -- a case of unbounded time between calls.
239 -- This polling interface may be used for instrumentation or debugging
240 -- purposes (e.g. implementing watchpoints in software or in the debugger).
242 -- In the GNAT technology itself, this interface is used to implement
243 -- immediate aynschronous transfer of control and immediate abort on
244 -- targets which do not provide for one thread interrupting another.
246 -- Note: this used to be in a separate unit called System.Poll, but that
247 -- caused horrible circular elaboration problems between System.Poll and
248 -- Ada.Exceptions. One way of solving such circularities is unification!
251 -- Check for asynchronous abort. Note that we do not inline the body.
252 -- This makes the interface more useful for debugging purposes.
254 --------------------------
255 -- Exception_Occurrence --
256 --------------------------
258 package TBE
renames System
.Traceback_Entries
;
260 Max_Tracebacks
: constant := 50;
261 -- Maximum number of trace backs stored in exception occurrence
263 type Tracebacks_Array
is array (1 .. Max_Tracebacks
) of TBE
.Traceback_Entry
;
264 -- Traceback array stored in exception occurrence
266 type Exception_Occurrence
is record
268 -- Exception_Identity for this exception occurrence
269 -- WARNING System.System.Finalization_Implementation.Finalize_List
270 -- relies on the fact that this field is always first in the exception
273 Msg_Length
: Natural := 0;
274 -- Length of message (zero = no message)
276 Msg
: String (1 .. Exception_Msg_Max_Length
);
277 -- Characters of message
279 Cleanup_Flag
: Boolean := False;
280 -- The cleanup flag is normally False, it is set True for an exception
281 -- occurrence passed to a cleanup routine, and will still be set True
282 -- when the cleanup routine does a Reraise_Occurrence call using this
283 -- exception occurrence. This is used to avoid recording a bogus trace
284 -- back entry from this reraise call.
286 Exception_Raised
: Boolean := False;
287 -- Set to true to indicate that this exception occurrence has actually
288 -- been raised. When an exception occurrence is first created, this is
289 -- set to False, then when it is processed by Raise_Current_Exception,
290 -- it is set to True. If Raise_Current_Exception is used to raise an
291 -- exception for which this flag is already True, then it knows that
292 -- it is dealing with the reraise case (which is useful to distinguish
293 -- for exception tracing purposes).
296 -- Partition_Id for partition raising exception
298 Num_Tracebacks
: Natural range 0 .. Max_Tracebacks
:= 0;
299 -- Number of traceback entries stored
301 Tracebacks
: Tracebacks_Array
;
302 -- Stored tracebacks (in Tracebacks (1 .. Num_Tracebacks))
304 Private_Data
: System
.Address
:= System
.Null_Address
;
305 -- Field used by low level exception mechanism to store specific data.
306 -- Currently used by the GCC exception mechanism to store a pointer to
307 -- a GNAT_GCC_Exception.
310 function "=" (Left
, Right
: Exception_Occurrence
) return Boolean
312 -- Don't allow comparison on exception occurrences, we should not need
313 -- this, and it would not work right, because of the Msg and Tracebacks
314 -- fields which have unused entries not copied by Save_Occurrence.
316 function EO_To_String
(X
: Exception_Occurrence
) return String;
317 function String_To_EO
(S
: String) return Exception_Occurrence
;
318 pragma Stream_Convert
(Exception_Occurrence
, String_To_EO
, EO_To_String
);
319 -- Functions for implementing Exception_Occurrence stream attributes
321 Null_Occurrence
: constant Exception_Occurrence
:= (
324 Msg
=> (others => ' '),
325 Cleanup_Flag
=> False,
326 Exception_Raised
=> False,
329 Tracebacks
=> (others => TBE
.Null_TB_Entry
),
330 Private_Data
=> System
.Null_Address
);