1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
5 -- G N A T . E X C E P T I O N _ A C T I O N S --
9 -- Copyright (C) 2002-2024, Free Software Foundation, Inc. --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. --
18 -- As a special exception under Section 7 of GPL version 3, you are granted --
19 -- additional permissions described in the GCC Runtime Library Exception, --
20 -- version 3.1, as published by the Free Software Foundation. --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
30 ------------------------------------------------------------------------------
32 -- This package provides support for callbacks on exceptions as well as
33 -- exception-related utility subprograms of possible interest together with
34 -- exception actions or more generally.
36 -- The callbacks are called immediately when either a specific exception,
37 -- or any exception, is raised, before any other actions taken by raise, in
38 -- particular before any unwinding of the stack occurs.
40 -- Callbacks for specific exceptions are registered through calls to
41 -- Register_Id_Action. Here is an example of code that uses this package to
42 -- automatically core dump when the exception Constraint_Error is raised.
44 -- Register_Id_Action (Constraint_Error'Identity, Core_Dump'Access);
46 -- Subprograms are also provided to list the currently registered exceptions,
47 -- or to convert from a string to an exception id.
49 -- This package can easily be extended, for instance to provide a callback
50 -- whenever an exception matching a regular expression is raised. The idea
51 -- is to register a global action, called whenever any exception is raised.
52 -- Dispatching can then be done directly in this global action callback.
54 with Ada
.Exceptions
; use Ada
.Exceptions
;
56 package GNAT
.Exception_Actions
is
58 type Exception_Action
is access
59 procedure (Occurrence
: Exception_Occurrence
);
60 pragma Favor_Top_Level
(Exception_Action
);
61 -- General callback type whenever an exception is raised. The callback
62 -- procedure must not propagate an exception (execution of the program
63 -- is erroneous if such an exception is propagated).
65 procedure Register_Global_Action
(Action
: Exception_Action
);
66 -- Action will be called whenever an exception is raised. Only one such
67 -- action can be registered at any given time, and registering a new action
68 -- will override any previous action that might have been registered.
70 -- Action is called before the exception is propagated to user's code.
71 -- If Action is null, this will in effect cancel all exception actions.
73 procedure Register_Global_Unhandled_Action
(Action
: Exception_Action
);
74 -- Similar to Register_Global_Action, called on unhandled exceptions only
76 procedure Register_Id_Action
78 Action
: Exception_Action
);
79 -- Action will be called whenever an exception of type Id is raised. Only
80 -- one such action can be registered for each exception id, and registering
81 -- a new action will override any previous action registered for this
82 -- Exception_Id. Program_Error is raised if Id is Null_Id.
84 function Name_To_Id
(Name
: String) return Exception_Id
;
85 -- Convert an exception name to an exception id. Null_Id is returned
86 -- if no such exception exists. Name must be an all upper-case string,
87 -- or the exception will not be found. The exception name must be fully
88 -- qualified (but not including Standard). It is not possible to convert
89 -- an exception that is declared within an unlabeled block.
91 -- Note: All non-predefined exceptions will return Null_Id for programs
92 -- compiled with pragma Restrictions (No_Exception_Registration).
94 function Is_Foreign_Exception
(E
: Exception_Occurrence
) return Boolean;
95 -- Tell whether the exception occurrence E represents a foreign exception,
96 -- such as one raised in C++ and caught by a when others choice in Ada.
98 function Registered_Exceptions_Count
return Natural;
99 -- Return the number of exceptions that have been registered so far.
100 -- Exceptions declared locally will not appear in this list until their
101 -- block has been executed at least once.
103 -- Note: The count includes only predefined exceptions for programs
104 -- compiled with pragma Restrictions (No_Exception_Registration).
106 type Exception_Id_Array
is array (Natural range <>) of Exception_Id
;
108 procedure Get_Registered_Exceptions
109 (List
: out Exception_Id_Array
;
111 -- Return the list of registered exceptions.
112 -- Last is the index in List of the last exception returned.
114 -- An exception is registered the first time the block containing its
115 -- declaration is elaborated. Exceptions defined at library-level are
116 -- therefore immediately visible, whereas exceptions declared in local
117 -- blocks will not be visible until the block is executed at least once.
119 -- Note: The list contains only the predefined exceptions if the program
120 -- is compiled with pragma Restrictions (No_Exception_Registration);
122 procedure Core_Dump
(Occurrence
: Exception_Occurrence
);
123 -- Dump memory (called a core dump in some systems) if supported by the
124 -- OS (most unix systems), and abort execution of the application. Under
125 -- Windows this procedure will not dump the memory, it will only abort
128 end GNAT
.Exception_Actions
;