11.4.1 The Package Exceptions
Static Semantics
The following language-defined
library package exists:
{
AI95-00362-01}
{
AI95-00400-01}
{
AI95-00438-01}
{
AI12-0241-1}
{
AI12-0302-1}
{
AI12-0399-1}
with Ada.Streams;
package Ada.Exceptions
with Preelaborate, Nonblocking, Global =>
in out synchronized is
type Exception_Id
is private
with Preelaborable_Initialization;
Null_Id :
constant Exception_Id;
function Exception_Name(Id : Exception_Id)
return String;
function Wide_Exception_Name(Id : Exception_Id)
return Wide_String;
function Wide_Wide_Exception_Name(Id : Exception_Id)
return Wide_Wide_String;
{
AI95-00362-01}
{
AI12-0399-1}
type Exception_Occurrence
is limited private
with Preelaborable_Initialization;
type Exception_Occurrence_Access
is access all Exception_Occurrence;
Null_Occurrence :
constant Exception_Occurrence;
{
AI95-00329-01}
{
AI05-0229-1}
procedure Raise_Exception(E :
in Exception_Id;
Message :
in String := "")
with No_Return;
function Exception_Message(X : Exception_Occurrence)
return String;
procedure Reraise_Occurrence(X :
in Exception_Occurrence);
{
AI95-00400-01}
function Exception_Identity(X : Exception_Occurrence)
return Exception_Id;
function Exception_Name(X : Exception_Occurrence)
return String;
--
Same as Exception_Name(Exception_Identity(X)).
function Wide_Exception_Name(X : Exception_Occurrence)
return Wide_String;
--
Same as Wide_Exception_Name(Exception_Identity(X)).
function Wide_Wide_Exception_Name(X : Exception_Occurrence)
return Wide_Wide_String;
--
Same as Wide_Wide_Exception_Name(Exception_Identity(X)).
function Exception_Information(X : Exception_Occurrence)
return String;
{
AI95-00438-01}
procedure Save_Occurrence(Target :
out Exception_Occurrence;
Source :
in Exception_Occurrence);
function Save_Occurrence(Source : Exception_Occurrence)
return Exception_Occurrence_Access;
{
AI95-00438-01}
procedure Read_Exception_Occurrence
(Stream :
not null access Ada.Streams.Root_Stream_Type'Class;
Item :
out Exception_Occurrence);
procedure Write_Exception_Occurrence
(Stream :
not null access Ada.Streams.Root_Stream_Type'Class;
Item :
in Exception_Occurrence);
{
AI95-00438-01}
for Exception_Occurrence'Read
use Read_Exception_Occurrence;
for Exception_Occurrence'Write
use Write_Exception_Occurrence;
{
AI95-00438-01}
private
... --
not specified by the language
end Ada.Exceptions;
Each distinct exception is represented by a distinct
value of type Exception_Id. Null_Id does not represent any exception,
and is the default initial value of type Exception_Id. Each occurrence
of an exception is represented by a value of type Exception_Occurrence.
Null_Occurrence does not represent any exception occurrence, and is the
default initial value of type Exception_Occurrence.
For a
prefix
E that denotes an exception, the following attribute is defined:
E'Identity
E'Identity returns the unique
identity of the exception. The type of this attribute is Exception_Id.
Ramification: In a distributed program,
the identity is unique across an entire program, not just across a single
partition. Exception propagation works properly across RPC's. An exception
can be propagated from one partition to another, and then back to the
first, where its identity is known.
{
AI95-00361-01}
Raise_Exception raises a new occurrence of the identified exception.
Implementation defined: The information
returned by Exception_Message.
Discussion: {
AI05-0043-1}
There is Implementation Advice about the contents of this string for
language-defined checks.
raise E;
is equivalent
to this call to Raise_Exception:
Raise_Exception(E'Identity, Message => implementation-defined-string);
raise E with "some information";
is equivalent
to this call to Raise_Exception:
Raise_Exception(E'Identity, Message => "some information");
{
AI95-00361-01}
Reraise_Occurrence reraises the specified exception occurrence.
Ramification:
The following handler:
when others =>
Cleanup;
raise;
is equivalent
to this one:
when X : others =>
Cleanup;
Reraise_Occurrence(X);
Exception_Identity returns the identity of the exception
of the occurrence.
{
AI95-00400-01}
The Wide_Wide_Exception_Name functions return the full expanded name
of the exception, in upper case, starting with a root library unit. For
an exception declared immediately within package Standard, the
defining_identifier
is returned. The result is implementation defined if the exception is
declared within an unnamed
block_statement.
Ramification: See the Implementation
Permission below.
Implementation defined: The result of
Exceptions.Wide_Wide_Exception_Name for exceptions declared within an
unnamed
block_statement.
Ramification: Note that we're talking
about the name of the exception, not the name of the occurrence.
{
AI95-00400-01}
The Exception_Name functions (respectively, Wide_Exception_Name) return
the same sequence of graphic characters as that defined for Wide_Wide_Exception_Name,
if all the graphic characters are defined in Character (respectively,
Wide_Character); otherwise, the sequence of characters is implementation
defined, but no shorter than that returned by Wide_Wide_Exception_Name
for the same value of the argument.
Implementation defined: The sequence
of characters of the value returned by Exceptions.Exception_Name (respectively,
Exceptions.Wide_Exception_Name) when some of the graphic characters of
Exceptions.Wide_Wide_Exception_Name are not defined in Character (respectively,
Wide_Character).
{
AI95-00378-01}
{
AI95-00417-01}
The string returned by the Exception_Name, Wide_Exception_Name, and Wide_Wide_Exception_Name
functions has lower bound 1.
{
AI95-00378-01}
Exception_Information returns implementation-defined information about
the exception occurrence. The returned string has lower bound 1.
Implementation defined: The information
returned by Exception_Information.
{
AI95-00241-01}
{
AI95-00446-01}
Reraise_Occurrence has no effect in the case of Null_Occurrence. Raise_Exception
and Exception_Name raise Constraint_Error for a Null_Id. Exception_Message,
Exception_Name, and Exception_Information raise Constraint_Error for
a Null_Occurrence. Exception_Identity applied to Null_Occurrence returns
Null_Id.
Ramification: {
AI95-00241-01}
Null_Occurrence can be tested for by comparing Exception_Identity(Occurrence)
to Null_Id.
Discussion: {
AI95-00446-01}
Raise_Exception was changed so that it always raises an exception and
thus can be a No_Return procedure. A similar change was not made for
Reraise_Occurrence, as doing so was determined to be a significant incompatibility.
It is not unusual to pass an Exception_Occurrence to other code to delay
raising it. If there was no exception, passing Null_Occurrence works
fine (nothing is raised). Moreover, as there is no test for Null_Occurrence
in Ada 95, this is the only way to write such code without using additional
flags. Breaking this sort of code is unacceptable.
The Save_Occurrence procedure copies the Source to
the Target. The Save_Occurrence function uses an
allocator
of type Exception_Occurrence_Access to create a new object, copies the
Source to this new object, and returns an access value designating this
new object; [the result may be deallocated using an instance of Unchecked_Deallocation.]
Ramification: It's OK to pass Null_Occurrence
to the Save_Occurrence subprograms; they don't raise an exception, but
simply save the Null_Occurrence.
{
AI95-00438-01}
Write_Exception_Occurrence writes a representation of an exception occurrence
to a stream; Read_Exception_Occurrence reconstructs an exception occurrence
from a stream (including one written in a different partition).
Ramification: {
AI12-0005-1}
These routines are used to define the stream attributes (see
13.13.2)
for Exception_Occurrence.
The identity of the exception, as well as the
Exception_Name and Exception_Message, have to be preserved across partitions.
The string returned by Exception_Name or Exception_Message
on the result of calling the Read attribute on a given stream has to
be the same as the value returned by calling the corresponding function
on the exception occurrence that was written into the stream with the
Write attribute. The string returned by Exception_Information need not
be the same, since it is implementation defined anyway.
Reason: This is important for supporting
writing exception occurrences to external files for post-mortem analysis,
as well as propagating exceptions across remote subprogram calls in a
distributed system (see
E.4).
Paragraph 16 was
deleted.
Implementation Permissions
An implementation of Exception_Name in a space-constrained
environment may return the
defining_identifier
instead of the full expanded name.
The string returned by Exception_Message may be truncated
(to no less than 200 characters) by the Save_Occurrence procedure [(not
the function)], the Reraise_Occurrence procedure, and the re-raise statement.
Reason: The reason for allowing truncation
is to ease implementations. The reason for choosing the number 200 is
that this is the minimum source line length that implementations have
to support, and this feature seems vaguely related since it's usually
a “one-liner”. Note that an implementation is allowed to
do this truncation even if it supports arbitrarily long lines.
Implementation Advice
Exception_Message (by default) and Exception_Information
should produce information useful for debugging. Exception_Message should
be short (about one line), whereas Exception_Information can be long.
Exception_Message should not include the Exception_Name. Exception_Information
should include both the Exception_Name and the Exception_Message.
Implementation Advice: Exception_Information
should provide information useful for debugging, and should include the
Exception_Name and Exception_Message.
Implementation Advice: Exception_Message
by default should be short, provide information useful for debugging,
and should not include the Exception_Name.
Reason: It may seem strange to define
two subprograms whose semantics is implementation defined. The idea is
that a program can print out debugging/error-logging information in a
portable way. The program is portable in the sense that it will work
in any implementation; it might print out different information, but
the presumption is that the information printed out is appropriate for
debugging/error analysis on that system.
Implementation Note: As an example, Exception_Information
might include information identifying the location where the exception
occurred, and, for predefined exceptions, the specific kind of language-defined
check that failed. There is an implementation trade-off here, between
how much information is represented in an Exception_Occurrence, and how
much can be passed through a re-raise.
The string returned should be in a form suitable
for printing to an error log file. This means that it might need to contain
line-termination control characters with implementation-defined I/O semantics.
The string should neither start nor end with a newline.
If an implementation chooses to provide additional
functionality related to exceptions and their occurrences, it should
do so by providing one or more children of Ada.Exceptions.
Note that exceptions behave as if declared at
library level; there is no “natural scope” for an exception;
an exception always exists. Hence, there is no harm in saving an exception
occurrence in a data structure, and reraising it later. The reraise has
to occur as part of the same program execution, so saving an exception
occurrence in a file, reading it back in from a different program execution,
and then reraising it is not required to work. This is similar to I/O
of access types. Note that it is possible to use RPC to propagate exceptions
across partitions.
Here's one way
to implement Exception_Occurrence in the private part of the package.
Using this method, an implementation need store only the actual number
of characters in exception messages. If the user always uses small messages,
then exception occurrences can be small. If the user never uses messages,
then exception occurrences can be smaller still:
type Exception_Occurrence(Message_Length : Natural := 200) is
limited record
Id : Exception_Id;
Message : String(1..Message_Length);
end record;
At the point where
an exception is raised, an Exception_Occurrence can be allocated on the
stack with exactly the right amount of space for the message —
none for an empty message. This is just like declaring a constrained
object of the type:
Temp : Exception_Occurrence(10); -- for a 10-character message
After finding the appropriate handler, the stack
can be cut back, and the Temp copied to the right place. This is similar
to returning an unknown-sized object from a function. It is not necessary
to allocate the maximum possible size for every Exception_Occurrence.
If, however, the user declares an Exception_Occurrence object, the discriminant
will be permanently set to 200. The Save_Occurrence procedure would then
truncate the Exception_Message. Thus, nothing is lost until the user
tries to save the occurrence. If the user is willing to pay the cost
of heap allocation, the Save_Occurrence function can be used instead.
Note that any arbitrary-sized implementation-defined
Exception_Information can be handled in a similar way. For example, if
the Exception_Occurrence includes a stack traceback, a discriminant can
control the number of stack frames stored. The traceback would be truncated
or entirely deleted by the Save_Occurrence procedure — as the implementation
sees fit.
If the internal representation involves pointers
to data structures that might disappear, it would behoove the implementation
to implement it as a controlled type, so that assignment can either copy
the data structures or else null out the pointers. Alternatively, if
the data structures being pointed at are in a task control block, the
implementation could keep a unique sequence number for each task, so
it could tell when a task's data structures no longer exist.
Using the above method, heap space is never
allocated unless the user calls the Save_Occurrence function.
An alternative
implementation would be to store the message strings on the heap when
the exception is raised. (It could be the global heap, or it could be
a special heap just for this purpose — it doesn't matter.) This
representation would be used only for choice parameters. For normal user-defined
exception occurrences, the Save_Occurrence procedure would copy the message
string into the occurrence itself, truncating as necessary. Thus, in
this implementation, Exception_Occurrence would be implemented as a variant
record:
type Exception_Occurrence_Kind is (Normal, As_Choice_Param);
type Exception_Occurrence(Kind : Exception_Occurrence_Kind := Normal) is
limited record
case Kind is
when Normal =>
... -- space for 200 characters
when As_Choice_Param =>
... -- pointer to heap string
end case;
end record;
Exception_Occurrences created by the run-time
system during exception raising would be As_Choice_Param. User-declared
ones would be Normal — the user cannot see the discriminant, and
so cannot set it to As_Choice_Param. The strings in the heap would be
freed upon completion of the handler.
This alternative implementation corresponds
to a heap-based implementation of functions returning unknown-sized results.
One possible implementation
of Reraise_Occurrence is as follows:
procedure Reraise_Occurrence(X : in Exception_Occurrence) is
begin
Raise_Exception(Identity(X), Exception_Message(X));
end Reraise_Occurrence;
However, some implementations may wish to retain
more information across a re-raise — a stack traceback, for example.
Ramification: Note that Exception_Occurrence
is a definite subtype. Hence, values of type Exception_Occurrence may
be written to an error log for later analysis, or may be passed to subprograms
for immediate error analysis.
NOTE {
AI12-0021-1}
UTF-8 encoding (see
A.4.11) can be used
to represent non-ASCII characters in exception messages.
Extensions to Ada 83
The Identity attribute of
exceptions is new, as is the package Exceptions.
Inconsistencies With Ada 95
{
AI95-00241-01}
Amendment Correction: Exception_Identity of
an Exception_Occurrence now is defined to return Null_Id for Null_Occurrence,
rather than raising Constraint_Error. This provides a simple way to test
for Null_Occurrence. We expect that programs that need Constraint_Error
raised will be very rare; they can be easily fixed by explicitly testing
for Null_Id or by using Exception_Name instead.
{
AI95-00378-01}
{
AI95-00417-01}
Amendment Correction: We now define the lower bound of the string
returned from [[Wide_]Wide_]Exception_Name, Exception_Message, and Exception_Information.
This makes working with the returned string easier, and is consistent
with many other string-returning functions in Ada. This is technically
an inconsistency; if a program depended on some other lower bound for
the string returned from one of these functions, it could fail when compiled
with Ada 2005. Such code is not portable even between Ada 95 implementations,
so it should be very rare.
{
AI95-00446-01}
Amendment Correction: Raise_Exception now raises Constraint_Error
if passed Null_Id. This means that it always raises an exception, and
thus we can apply pragma No_Return to it. We expect that programs that
call Raise_Exception with Null_Id will be rare, and programs that do
that and expect no exception to be raised will be rarer; such programs
can be easily fixed by explicitly testing for Null_Id before calling
Raise_Exception.
Incompatibilities With Ada 95
{
AI95-00400-01}
{
AI95-00438-01}
{
AI05-0005-1}
Functions Wide_Exception_Name and Wide_Wide_Exception_Name,
and procedures Read_Exception_Occurrence and Write_Exception_Occurrence
are added to Exceptions. If Exceptions is referenced in a
use_clause,
and an entity
E with the same
defining_identifier
as a new entity in Exceptions is defined in a package that is also referenced
in a
use_clause,
the entity
E may no longer be use-visible, resulting in errors.
This should be rare and is easily fixed if it does occur.
Extensions to Ada 95
{
AI95-00362-01}
The package Exceptions is preelaborated, and types
Exception_Id and Exception_Occurrence have preelaborable initialization,
allowing this package to be used in preelaborated units.
Wording Changes from Ada 95
{
AI95-00361-01}
The meaning of Exception_Message is reworded to reflect that the string
can come from a
raise_statement
as well as a call of Raise_Exception.
{
AI95-00400-01}
Added Wide_Exception_Name and Wide_Wide_Exception_Name because identifiers
can now contain characters outside of Latin-1.
Wording Changes from Ada 2005
{
AI05-0043-1}
Correction: Added explicit wording that the exception message
for language-defined checks is unspecified. The old wording appeared
inclusive, but it was not.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
