[Home] [Prev] [Next] [Index]

11.4 Exception Handling

11.4 Exception Handling

1
[When an exception occurrence is raised, normal program execution is abandoned and control is transferred to an applicable exception_handler, if any. To handle an exception occurrence is to respond to the exceptional event. To propagate an exception occurrence is to raise it again in another context; that is, to fail to respond to the exceptional event in the present context.]

1.a
Ramification: In other words, if the execution of a given construct raises an exception, but does not handle it, the exception is propagated to an enclosing execution (except in the case of a task_body).

1.b
Propagation involves re-raising the same exception occurrence (assuming the implementation has not taken advantage of the Implementation Permission of 11.3). For example, calling an entry of an uncallable task raises Tasking_Error; this is not propagation.

Dynamic Semantics

2
Within a given task, if the execution of construct a is defined by this International Standardto consist (in part) of the execution of construct b, then while b is executing, the execution of a is said to dynamically enclose the execution of b. The innermost dynamically enclosing execution of a given execution is the dynamically enclosing execution that started most recently.

2.a
To be honest: If the execution of a dynamically encloses that of b, then we also say that the execution of b is included in the execution of a.

2.b
Ramification: Examples: The execution of an if_statement dynamically encloses the evaluation of the condition after the if (during that evaluation). (Recall that "execution" includes both "elaboration" and "evaluation", as well as other executions.) The evaluation of a function call dynamically encloses the execution of the sequence_of_statements of the function_body (during that execution).  Note that, due to recursion, several simultaneous executions of the same construct can be occurring at once during the execution of a particular task.

2.c
Dynamically enclosing is not defined across task boundaries; a task's execution does not include the execution of any other tasks.

2.d
Dynamically enclosing is only defined for executions that are occurring at a given moment in time; if an if_statement is currently executing the sequence_of_statements after then, then the evaluation of the condition is no longer dynamically enclosed by the execution of the if_statement (or anything else).

3
When an exception occurrence is raised by the execution of a given construct, the rest of the execution of that construct is abandoned; that is, any portions of the execution that have not yet taken place are not performed. The construct is first completed, and then left, as explained in 7.6.1. Then:

4 ·
If the construct is a task_body, the exception does not propagate further;

4.a
Ramification: When an exception is raised by the execution of a task_body, there is no dynamically enclosing execution, so the exception does not propagate any further. If the exception occurred during the activation of the task, then the activator raises Tasking_Error, as explained in 9.2, "Task Execution - Task Activation", but we don't define that as propagation; it's a special rule. Otherwise (the exception occurred during the execution of the handled_sequence_of_statements of the task), the task silently disappears. Thus, abnormal termination of tasks is not always considered to be an error.

5 ·
If the construct is the sequence_of_statements of a handled_sequence_of_statements that has a handler with a choice covering the exception, the occurrence is handled by that handler;

6 ·
Otherwise, the occurrence is propagated to the innermost dynamically enclosing execution, which means that the occurrence is raised again in that context.

6.a
To be honest: As shorthands, we refer to the propagation of an exception, and the propagation by a construct, if the execution of the construct propagates an exception occurrence.

7
When an occurrence is handled by a given handler, the choice_parameter_specification, if any, is first elaborated, which creates the choice parameter and initializes it to the occurrence. Then, the sequence_of_statements of the handler is executed; this execution replaces the abandoned portion of the execution of the sequence_of_statements.

7.a
Ramification: This "replacement" semantics implies that the handler can do pretty much anything the abandoned sequence could do; for example, in a function, the handler can execute a return_statement that applies to the function.

7.b
Ramification: The rules for exceptions raised in library units, main subprograms and partitions follow from the normal rules, plus the semantics of the environment task described in Section 10 (for example, the environment task of a partition elaborates library units and calls the main subprogram). If an exception is propagated by the main subprogram, it is propagated to the environment task, which then terminates abnormally, causing the partition to terminate abnormally. Although abnormal termination of tasks is not necessarily an error, abnormal termination of a partition due to an exception is an error.

NOTES

8 1
Note that exceptions raised in a declarative_part of a body are not handled by the handlers of the handled_sequence_of_statements of that body.

11.4.1 The Package Exceptions

Static Semantics

1
The following language-defined library package exists:

2
package Ada.Exceptions is

    type Exception_Id is private;
    Null_Id : constant Exception_Id;
    function Exception_Name(Id : Exception_Id) return String;

3
    type Exception_Occurrence is limited private;

    type Exception_Occurrence_Access is access all Exception_Occurrence;
    Null_Occurrence : constant Exception_Occurrence;

4
    procedure Raise_Exception(E : in Exception_Id; Message : in String := "");
    function Exception_Message(X : Exception_Occurrence) return String;
    procedure Reraise_Occurrence(X : in Exception_Occurrence);

5
    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 Exception_Information(X : Exception_Occurrence) return String;

6
    procedure Save_Occurrence(Target : out Exception_Occurrence;
                              Source : in Exception_Occurrence);
    function Save_Occurrence(Source : Exception_Occurrence)
                             return Exception_Occurrence_Access;
private
   ... --not specified by the language
end Ada.Exceptions;

7
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.

8
For a prefix E that denotes an exception, the following attribute is defined:

9
E'Identity E'Identity returns the unique identity of the exception. The type of this attribute is Exception_Id.

9.a
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.

10
Raise_Exception raises a new occurrence of the identified exception. In this case, Exception_Message returns the Message parameter of Raise_Exception. For a raise_statement with an exception_name, Exception_Message returns implementation-defined information about the exception occurrence. Reraise_Occurrence reraises the specified exception occurrence.

10.a
Implementation defined:  The information returned by Exception_Message.

10.b
Ramification: Given an exception E, the raise_statement:

10.c
raise E;

10.d
is equivalent to this call to Raise_Exception:

10.e
Raise_Exception(E'Identity, Message => implementation-defined-string);

10.f
The following handler:

10.g
when others =>
    Cleanup;
    raise;

10.h
is equivalent to this one:

10.i
when X : others =>
    Cleanup;
    Reraise_Occurrence(X);

11
Exception_Identity returns the identity of the exception of the occurrence.

12
The 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.

12.a
Ramification: See the Implementation Permission below.

12.b
To be honest: This name, as well as each prefix of it, does not denote a renaming_declaration.

12.c
Implementation defined:  The result of Exceptions.Exception_Name for types declared within an unnamed block_statement.

12.d
Ramification: Note that we're talking about the name of the exception, not the name of the occurrence.

13
Exception_Information returns implementation-defined information about the exception occurrence.

13.a
Implementation defined:  The information returned by Exception_Information.

14
Raise_Exception and Reraise_Occurrence have no effect in the case of Null_Id or Null_Occurrence. Exception_Message, Exception_Identity, Exception_Name, and Exception_Information raise Constraint_Error for a Null_Id or Null_Occurrence.

15
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.]

15.a
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.

Implementation Requirements

16
The implementation of the Write attribute (see 13.13.2) of Exception_Occurrence shall support writing a representation of an exception occurrence to a stream; the implementation of the Read attribute of Exception_Occurrence shall support reconstructing an exception occurrence from a stream (including one written in a different partition).

16.a
Ramification: The identity of the exception, as well as the Exception_Name and Exception_Message, have to be preserved across partitions.

16.b
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.

16.c
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).

Implementation Permissions

17
An implementation of Exception_Name in a space-constrained environment may return the defining_identifier instead of the full expanded name.

18
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.

18.a
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

19
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.

19.a
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.

19.b
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.

19.c
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.

19.d
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.

19.e
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.

19.f
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:

19.g
type Exception_Occurrence(Message_Length : Natural := 200) is
    limited record
        Id : Exception_Id;
        Message : String(1..Message_Length);
    end record;

19.h
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:

19.i
Temp : Exception_Occurrence(10); --for a 10-character message

19.j
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.

19.k
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.

19.l
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.

19.m
Using the above method, heap space is never allocated unless the user calls the Save_Occurrence function.

19.n
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:

19.o
type Exception_Occurrence_Kind is (Normal, As_Choice_Param);

19.p
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;

19.q
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.

19.r
This alternative implementation corresponds to a heap-based implementation of functions returning unknown-sized results.

19.s
One possible implementation of Reraise_Occurrence is as follows:

19.t
procedure Reraise_Occurrence(X : in Exception_Occurrence) is
begin
    Raise_Exception(Identity(X), Exception_Message(X));
end Reraise_Occurrence;

19.u
However, some implementations may wish to retain more information across a re-raise - a stack traceback, for example.

19.v
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.

19.w
Implementation Note: If an implementation chooses to have a mode in which it supports non-Latin-1 characters in identifiers, then it needs to define what the above functions return in the case where the name of an exception contains such a character.

Extensions to Ada 83

19.x
The Identity attribute of exceptions is new, as is the package Exceptions.

11.4.2 Example of Exception Handling

Examples

1
Exception handling may be used to separate the detection of an error from the response to that error:

2
with Ada.Exceptions;
use Ada;
package File_System is
    type File_Handle is limited private;

3
    File_Not_Found : exception;
    procedure Open(F : in out File_Handle; Name : String);
        --raises File_Not_Found if named file does not exist

4
    End_Of_File : exception;
    procedure Read(F : in out File_Handle; Data : out Data_Type);
        --raises End_Of_File if the file is not open

5
    ...
end File_System;

6
package body File_System is
    procedure Open(F : in out File_Handle; Name : String) is
    begin
        if File_Exists(Name) then
            ...
        else
            Exceptions.Raise_Exception(File_Not_Found'Identity,
                                      "File not found: " & Name & ".");
        end if;
    end Open;

7
    procedure Read(F : in out File_Handle; Data : out Data_Type) is
    begin
        if F.Current_Position <= F.Last_Position then
            ...
        else
            raise End_Of_File;
        end if;
    end Read;

8
    ...

9
end File_System;

10
with Ada.Text_IO;
with Ada.Exceptions;
with File_System; use File_System;
use Ada;
procedure Main is
begin
    ... --call operations in File_System
exception
    when End_Of_File =>
        Close(Some_File);
    when Not_Found_Error : File_Not_Found =>
        Text_IO.Put_Line(Exceptions.Exception_Message(Not_Found_Error));
    when The_Error : others =>
        Text_IO.Put_Line("Unknown error:");
        if Verbosity_Desired then
            Text_IO.Put_Line(Exceptions.Exception_Information(The_Error));
        else
            Text_IO.Put_Line(Exceptions.Exception_Name(The_Error));
            Text_IO.Put_Line(Exceptions.Exception_Message(The_Error));
        end if;
        raise;
end Main;

11
In the above example, the File_System package contains information about detecting certain exceptional situations, but it does not specify how to handle those situations. Procedure Main specifies how to handle them; other clients of File_System might have different handlers, even though the exceptional situations arise from the same basic causes.

Wording Changes From Ada 83

11.a
The sections labeled "Exceptions Raised During ..." are subsumed by this clause, and by parts of Section 9.



[Home] [Prev] [Next] [Index]

documentation@rational.com
Copyright © 1993-1998, Rational Software Corporation.   All rights reserved.