1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- A D A . E X C E P T I O N S --
9 -- Copyright (C) 1992-2009, 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 3, 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. --
22 -- As a special exception under Section 7 of GPL version 3, you are granted --
23 -- additional permissions described in the GCC Runtime Library Exception, --
24 -- version 3.1, as published by the Free Software Foundation. --
26 -- You should have received a copy of the GNU General Public License and --
27 -- a copy of the GCC Runtime Library Exception along with this program; --
28 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
29 -- <http://www.gnu.org/licenses/>. --
31 -- GNAT was originally developed by the GNAT team at New York University. --
32 -- Extensive contributions were provided by Ada Core Technologies Inc. --
34 ------------------------------------------------------------------------------
36 -- This version of Ada.Exceptions fully supports both Ada 95 and Ada 2005.
37 -- It is used in all situations except for the build of the compiler and
38 -- other basic tools. For these latter builds, we use an Ada 95-only version.
40 -- The reason for this splitting off of a separate version is that bootstrap
41 -- compilers often will be used that do not support Ada 2005 features, and
42 -- Ada.Exceptions is part of the compiler sources.
45 -- We must turn polling off for this unit, because otherwise we get
46 -- elaboration circularities with ourself.
49 with System
.Parameters
;
50 with System
.Standard_Library
;
51 with System
.Traceback_Entries
;
53 with Ada
.Unchecked_Conversion
;
55 package Ada
.Exceptions
is
56 pragma Warnings
(Off
);
57 pragma Preelaborate_05
;
59 -- In accordance with Ada 2005 AI-362. The warnings pragmas are so that we
60 -- can compile this using older compiler versions, which will ignore the
61 -- pragma, which is fine for the bootstrap.
63 type Exception_Id
is private;
64 pragma Preelaborable_Initialization
(Exception_Id
);
66 Null_Id
: constant Exception_Id
;
68 type Exception_Occurrence
is limited private;
69 pragma Preelaborable_Initialization
(Exception_Occurrence
);
71 type Exception_Occurrence_Access
is access all Exception_Occurrence
;
73 Null_Occurrence
: constant Exception_Occurrence
;
75 function Exception_Name
(Id
: Exception_Id
) return String;
77 function Exception_Name
(X
: Exception_Occurrence
) return String;
79 function Wide_Exception_Name
80 (Id
: Exception_Id
) return Wide_String;
81 pragma Ada_05
(Wide_Exception_Name
);
83 function Wide_Exception_Name
84 (X
: Exception_Occurrence
) return Wide_String;
85 pragma Ada_05
(Wide_Exception_Name
);
87 function Wide_Wide_Exception_Name
88 (Id
: Exception_Id
) return Wide_Wide_String
;
89 pragma Ada_05
(Wide_Wide_Exception_Name
);
91 function Wide_Wide_Exception_Name
92 (X
: Exception_Occurrence
) return Wide_Wide_String
;
93 pragma Ada_05
(Wide_Wide_Exception_Name
);
95 procedure Raise_Exception
(E
: Exception_Id
; Message
: String := "");
96 pragma No_Return
(Raise_Exception
);
97 -- Note: In accordance with AI-466, CE is raised if E = Null_Id
99 function Exception_Message
(X
: Exception_Occurrence
) return String;
101 procedure Reraise_Occurrence
(X
: Exception_Occurrence
);
102 -- Note: it would be really nice to give a pragma No_Return for this
103 -- procedure, but it would be wrong, since Reraise_Occurrence does return
104 -- if the argument is the null exception occurrence. See also procedure
105 -- Reraise_Occurrence_Always in the private part of this package.
107 function Exception_Identity
(X
: Exception_Occurrence
) return Exception_Id
;
109 function Exception_Information
(X
: Exception_Occurrence
) return String;
110 -- The format of the exception information is as follows:
112 -- exception name (as in Exception_Name)
113 -- message (or a null line if no message)
115 -- 0xyyyyyyyy 0xyyyyyyyy ...
117 -- The lines are separated by a ASCII.LF character
119 -- The nnnn is the partition Id given as decimal digits
121 -- The 0x... line represents traceback program counter locations,
122 -- in order with the first one being the exception location.
124 -- Note on ordering: the compiler uses the Save_Occurrence procedure, but
125 -- not the function from Rtsfind, so it is important that the procedure
126 -- come first, since Rtsfind finds the first matching entity.
128 procedure Save_Occurrence
129 (Target
: out Exception_Occurrence
;
130 Source
: Exception_Occurrence
);
132 function Save_Occurrence
133 (Source
: Exception_Occurrence
)
134 return Exception_Occurrence_Access
;
136 -- Ada 2005 (AI-438): The language revision introduces the following
137 -- subprograms and attribute definitions. We do not provide them
138 -- explicitly. instead, the corresponding stream attributes are made
139 -- available through a pragma Stream_Convert in the private part.
141 -- procedure Read_Exception_Occurrence
142 -- (Stream : not null access Ada.Streams.Root_Stream_Type'Class;
143 -- Item : out Exception_Occurrence);
145 -- procedure Write_Exception_Occurrence
146 -- (Stream : not null access Ada.Streams.Root_Stream_Type'Class;
147 -- Item : Exception_Occurrence);
149 -- for Exception_Occurrence'Read use Read_Exception_Occurrence;
150 -- for Exception_Occurrence'Write use Write_Exception_Occurrence;
153 package SSL
renames System
.Standard_Library
;
154 package SP
renames System
.Parameters
;
156 subtype EOA
is Exception_Occurrence_Access
;
158 Exception_Msg_Max_Length
: constant := SP
.Default_Exception_Msg_Max_Length
;
164 subtype Code_Loc
is System
.Address
;
165 -- Code location used in building exception tables and for call addresses
166 -- when propagating an exception. Values of this type are created by using
167 -- Label'Address or extracted from machine states using Get_Code_Loc.
169 Null_Loc
: constant Code_Loc
:= System
.Null_Address
;
170 -- Null code location, used to flag outer level frame
172 type Exception_Id
is new SSL
.Exception_Data_Ptr
;
174 function EId_To_String
(X
: Exception_Id
) return String;
175 function String_To_EId
(S
: String) return Exception_Id
;
176 pragma Stream_Convert
(Exception_Id
, String_To_EId
, EId_To_String
);
177 -- Functions for implementing Exception_Id stream attributes
179 Null_Id
: constant Exception_Id
:= null;
181 -------------------------
182 -- Private Subprograms --
183 -------------------------
185 function Current_Target_Exception
return Exception_Occurrence
;
187 (Ada
, Current_Target_Exception
,
188 "__gnat_current_target_exception");
189 -- This routine should return the current raised exception on targets which
190 -- have built-in exception handling such as the Java Virtual Machine. For
191 -- other targets this routine is simply ignored. Currently, only JGNAT
192 -- uses this. See 4jexcept.ads for details. The pragma Export allows this
193 -- routine to be accessed elsewhere in the run-time, even though it is in
194 -- the private part of this package (it is not allowed to be in the visible
195 -- part, since this is set by the reference manual).
197 function Exception_Name_Simple
(X
: Exception_Occurrence
) return String;
198 -- Like Exception_Name, but returns the simple non-qualified name of the
199 -- exception. This is used to implement the Exception_Name function in
200 -- Current_Exceptions (the DEC compatible unit). It is called from the
201 -- compiler generated code (using Rtsfind, which does not respect the
202 -- private barrier, so we can place this function in the private part
203 -- where the compiler can find it, but the spec is unchanged.)
205 procedure Raise_Exception_Always
(E
: Exception_Id
; Message
: String := "");
206 pragma No_Return
(Raise_Exception_Always
);
207 pragma Export
(Ada
, Raise_Exception_Always
, "__gnat_raise_exception");
208 -- This differs from Raise_Exception only in that the caller has determined
209 -- that for sure the parameter E is not null, and that therefore no check
210 -- for Null_Id is required. The expander converts Raise_Exception calls to
211 -- Raise_Exception_Always if it can determine this is the case. The Export
212 -- allows this routine to be accessed from Pure units.
214 procedure Raise_From_Signal_Handler
218 (Ada
, Raise_From_Signal_Handler
,
219 "ada__exceptions__raise_from_signal_handler");
220 pragma No_Return
(Raise_From_Signal_Handler
);
221 -- This routine is used to raise an exception from a signal handler. The
222 -- signal handler has already stored the machine state (i.e. the state that
223 -- corresponds to the location at which the signal was raised). E is the
224 -- Exception_Id specifying what exception is being raised, and M is a
225 -- pointer to a null-terminated string which is the message to be raised.
226 -- Note that this routine never returns, so it is permissible to simply
227 -- jump to this routine, rather than call it. This may be appropriate for
228 -- systems where the right way to get out of signal handler is to alter the
229 -- PC value in the machine state or in some other way ask the operating
230 -- system to return here rather than to the original location.
232 procedure Raise_From_Controlled_Operation
233 (X
: Ada
.Exceptions
.Exception_Occurrence
);
234 pragma No_Return
(Raise_From_Controlled_Operation
);
235 -- Raise Program_Error, providing information about X (an exception raised
236 -- during a controlled operation) in the exception message.
238 procedure Reraise_Occurrence_Always
(X
: Exception_Occurrence
);
239 pragma No_Return
(Reraise_Occurrence_Always
);
240 -- This differs from Raise_Occurrence only in that the caller guarantees
241 -- that for sure the parameter X is not the null occurrence, and that
242 -- therefore this procedure cannot return. The expander uses this routine
243 -- in the translation of a raise statement with no parameter (reraise).
245 procedure Reraise_Occurrence_No_Defer
(X
: Exception_Occurrence
);
246 pragma No_Return
(Reraise_Occurrence_No_Defer
);
247 -- Exactly like Reraise_Occurrence, except that abort is not deferred
248 -- before the call and the parameter X is known not to be the null
249 -- occurrence. This is used in generated code when it is known that abort
250 -- is already deferred.
252 -----------------------
253 -- Polling Interface --
254 -----------------------
256 -- The GNAT compiler has an option to generate polling calls to the Poll
257 -- routine in this package. Specifying the -gnatP option for a compilation
258 -- causes a call to Ada.Exceptions.Poll to be generated on every subprogram
259 -- entry and on every iteration of a loop, thus avoiding the possibility of
260 -- a case of unbounded time between calls.
262 -- This polling interface may be used for instrumentation or debugging
263 -- purposes (e.g. implementing watchpoints in software or in the debugger).
265 -- In the GNAT technology itself, this interface is used to implement
266 -- immediate asynchronous transfer of control and immediate abort on
267 -- targets which do not provide for one thread interrupting another.
269 -- Note: this used to be in a separate unit called System.Poll, but that
270 -- caused horrible circular elaboration problems between System.Poll and
271 -- Ada.Exceptions. One way of solving such circularities is unification!
274 -- Check for asynchronous abort. Note that we do not inline the body.
275 -- This makes the interface more useful for debugging purposes.
277 --------------------------
278 -- Exception_Occurrence --
279 --------------------------
281 package TBE
renames System
.Traceback_Entries
;
283 Max_Tracebacks
: constant := 50;
284 -- Maximum number of trace backs stored in exception occurrence
286 type Tracebacks_Array
is array (1 .. Max_Tracebacks
) of TBE
.Traceback_Entry
;
287 -- Traceback array stored in exception occurrence
289 type Exception_Occurrence
is record
291 -- Exception_Identity for this exception occurrence
293 -- WARNING System.System.Finalization_Implementation.Finalize_List
294 -- relies on the fact that this field is always first in the exception
297 Msg_Length
: Natural := 0;
298 -- Length of message (zero = no message)
300 Msg
: String (1 .. Exception_Msg_Max_Length
);
301 -- Characters of message
303 Cleanup_Flag
: Boolean := False;
304 -- The cleanup flag is normally False, it is set True for an exception
305 -- occurrence passed to a cleanup routine, and will still be set True
306 -- when the cleanup routine does a Reraise_Occurrence call using this
307 -- exception occurrence. This is used to avoid recording a bogus trace
308 -- back entry from this reraise call.
310 Exception_Raised
: Boolean := False;
311 -- Set to true to indicate that this exception occurrence has actually
312 -- been raised. When an exception occurrence is first created, this is
313 -- set to False, then when it is processed by Raise_Current_Exception,
314 -- it is set to True. If Raise_Current_Exception is used to raise an
315 -- exception for which this flag is already True, then it knows that
316 -- it is dealing with the reraise case (which is useful to distinguish
317 -- for exception tracing purposes).
320 -- Partition_Id for partition raising exception
322 Num_Tracebacks
: Natural range 0 .. Max_Tracebacks
:= 0;
323 -- Number of traceback entries stored
325 Tracebacks
: Tracebacks_Array
;
326 -- Stored tracebacks (in Tracebacks (1 .. Num_Tracebacks))
328 Private_Data
: System
.Address
:= System
.Null_Address
;
329 -- Field used by low level exception mechanism to store specific data.
330 -- Currently used by the GCC exception mechanism to store a pointer to
331 -- a GNAT_GCC_Exception.
334 function "=" (Left
, Right
: Exception_Occurrence
) return Boolean
336 -- Don't allow comparison on exception occurrences, we should not need
337 -- this, and it would not work right, because of the Msg and Tracebacks
338 -- fields which have unused entries not copied by Save_Occurrence.
340 function EO_To_String
(X
: Exception_Occurrence
) return String;
341 function String_To_EO
(S
: String) return Exception_Occurrence
;
342 pragma Stream_Convert
(Exception_Occurrence
, String_To_EO
, EO_To_String
);
343 -- Functions for implementing Exception_Occurrence stream attributes
345 Null_Occurrence
: constant Exception_Occurrence
:= (
348 Msg
=> (others => ' '),
349 Cleanup_Flag
=> False,
350 Exception_Raised
=> False,
353 Tracebacks
=> (others => TBE
.Null_TB_Entry
),
354 Private_Data
=> System
.Null_Address
);
356 -- Common binding to __builtin_longjmp for sjlj variants.
358 -- The builtin expects a pointer type for the jmpbuf address argument, and
359 -- System.Address doesn't work because this is really an integer type.
361 type Jmpbuf_Address
is access Character;
363 function To_Jmpbuf_Address
is new
364 Ada
.Unchecked_Conversion
(System
.Address
, Jmpbuf_Address
);
366 procedure builtin_longjmp
(buffer
: Jmpbuf_Address
; Flag
: Integer);
367 pragma No_Return
(builtin_longjmp
);
368 pragma Import
(Intrinsic
, builtin_longjmp
, "__builtin_longjmp");