|
111
|
1 ------------------------------------------------------------------------------
|
|
|
2 -- --
|
|
|
3 -- GNAT COMPILER COMPONENTS --
|
|
|
4 -- --
|
|
|
5 -- G N A T . E X C E P T I O N _ A C T I O N S --
|
|
|
6 -- --
|
|
|
7 -- S p e c --
|
|
|
8 -- --
|
|
145
|
9 -- Copyright (C) 2002-2019, Free Software Foundation, Inc. --
|
|
111
|
10 -- --
|
|
|
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. --
|
|
|
17 -- --
|
|
|
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. --
|
|
|
21 -- --
|
|
|
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/>. --
|
|
|
26 -- --
|
|
|
27 -- GNAT was originally developed by the GNAT team at New York University. --
|
|
|
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
|
|
|
29 -- --
|
|
|
30 ------------------------------------------------------------------------------
|
|
|
31
|
|
131
|
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.
|
|
111
|
35
|
|
131
|
36 -- The callbacks are called immediately when either a specific exception,
|
|
111
|
37 -- or any exception, is raised, before any other actions taken by raise, in
|
|
|
38 -- particular before any unwinding of the stack occurs.
|
|
|
39
|
|
|
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.
|
|
|
43
|
|
|
44 -- Register_Id_Action (Constraint_Error'Identity, Core_Dump'Access);
|
|
|
45
|
|
|
46 -- Subprograms are also provided to list the currently registered exceptions,
|
|
|
47 -- or to convert from a string to an exception id.
|
|
|
48
|
|
|
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.
|
|
|
53
|
|
|
54 with Ada.Exceptions; use Ada.Exceptions;
|
|
|
55
|
|
|
56 package GNAT.Exception_Actions is
|
|
|
57
|
|
|
58 type Exception_Action is access
|
|
|
59 procedure (Occurrence : Exception_Occurrence);
|
|
|
60 -- General callback type whenever an exception is raised. The callback
|
|
|
61 -- procedure must not propagate an exception (execution of the program
|
|
|
62 -- is erroneous if such an exception is propagated).
|
|
|
63
|
|
|
64 procedure Register_Global_Action (Action : Exception_Action);
|
|
|
65 -- Action will be called whenever an exception is raised. Only one such
|
|
|
66 -- action can be registered at any given time, and registering a new action
|
|
|
67 -- will override any previous action that might have been registered.
|
|
|
68 --
|
|
|
69 -- Action is called before the exception is propagated to user's code.
|
|
|
70 -- If Action is null, this will in effect cancel all exception actions.
|
|
|
71
|
|
|
72 procedure Register_Id_Action
|
|
|
73 (Id : Exception_Id;
|
|
|
74 Action : Exception_Action);
|
|
|
75 -- Action will be called whenever an exception of type Id is raised. Only
|
|
|
76 -- one such action can be registered for each exception id, and registering
|
|
|
77 -- a new action will override any previous action registered for this
|
|
|
78 -- Exception_Id. Program_Error is raised if Id is Null_Id.
|
|
|
79
|
|
|
80 function Name_To_Id (Name : String) return Exception_Id;
|
|
|
81 -- Convert an exception name to an exception id. Null_Id is returned
|
|
|
82 -- if no such exception exists. Name must be an all upper-case string,
|
|
|
83 -- or the exception will not be found. The exception name must be fully
|
|
|
84 -- qualified (but not including Standard). It is not possible to convert
|
|
|
85 -- an exception that is declared within an unlabeled block.
|
|
|
86 --
|
|
|
87 -- Note: All non-predefined exceptions will return Null_Id for programs
|
|
|
88 -- compiled with pragma Restriction (No_Exception_Registration)
|
|
|
89
|
|
131
|
90 function Is_Foreign_Exception (E : Exception_Occurrence) return Boolean;
|
|
|
91 -- Tell whether the exception occurrence E represents a foreign exception,
|
|
|
92 -- such as one raised in C++ and caught by a when others choice in Ada.
|
|
|
93
|
|
111
|
94 function Registered_Exceptions_Count return Natural;
|
|
|
95 -- Return the number of exceptions that have been registered so far.
|
|
|
96 -- Exceptions declared locally will not appear in this list until their
|
|
|
97 -- block has been executed at least once.
|
|
|
98 --
|
|
|
99 -- Note: The count includes only predefined exceptions for programs
|
|
|
100 -- compiled with pragma Restrictions (No_Exception_Registration).
|
|
|
101
|
|
|
102 type Exception_Id_Array is array (Natural range <>) of Exception_Id;
|
|
|
103
|
|
|
104 procedure Get_Registered_Exceptions
|
|
|
105 (List : out Exception_Id_Array;
|
|
|
106 Last : out Integer);
|
|
|
107 -- Return the list of registered exceptions.
|
|
|
108 -- Last is the index in List of the last exception returned.
|
|
|
109 --
|
|
|
110 -- An exception is registered the first time the block containing its
|
|
|
111 -- declaration is elaborated. Exceptions defined at library-level are
|
|
|
112 -- therefore immediately visible, whereas exceptions declared in local
|
|
|
113 -- blocks will not be visible until the block is executed at least once.
|
|
|
114 --
|
|
|
115 -- Note: The list contains only the predefined exceptions if the program
|
|
|
116 -- is compiled with pragma Restrictions (No_Exception_Registration);
|
|
|
117
|
|
|
118 procedure Core_Dump (Occurrence : Exception_Occurrence);
|
|
|
119 -- Dump memory (called a core dump in some systems) if supported by the
|
|
|
120 -- OS (most unix systems), and abort execution of the application. Under
|
|
|
121 -- Windows this procedure will not dump the memory, it will only abort
|
|
|
122 -- execution.
|
|
|
123
|
|
|
124 end GNAT.Exception_Actions;
|
