File : g-excact.ads
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 -- --
9 -- Copyright (C) 2002-2014, Free Software Foundation, Inc. --
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 -- --
19 -- --
20 -- --
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
32 -- This package provides support for callbacks on exceptions
33
34 -- These callbacks are called immediately when either a specific exception,
35 -- or any exception, is raised, before any other actions taken by raise, in
36 -- particular before any unwinding of the stack occurs.
37
38 -- Callbacks for specific exceptions are registered through calls to
39 -- Register_Id_Action. Here is an example of code that uses this package to
40 -- automatically core dump when the exception Constraint_Error is raised.
41
42 -- Register_Id_Action (Constraint_Error'Identity, Core_Dump'Access);
43
44 -- Subprograms are also provided to list the currently registered exceptions,
45 -- or to convert from a string to an exception id.
46
47 -- This package can easily be extended, for instance to provide a callback
48 -- whenever an exception matching a regular expression is raised. The idea
49 -- is to register a global action, called whenever any exception is raised.
50 -- Dispatching can then be done directly in this global action callback.
51
52 with Ada.Exceptions; use Ada.Exceptions;
53
54 package GNAT.Exception_Actions is
55
56 type Exception_Action is access
57 procedure (Occurrence : Exception_Occurrence);
58 -- General callback type whenever an exception is raised. The callback
59 -- procedure must not propagate an exception (execution of the program
60 -- is erroneous if such an exception is propagated).
61
62 procedure Register_Global_Action (Action : Exception_Action);
63 -- Action will be called whenever an exception is raised. Only one such
64 -- action can be registered at any given time, and registering a new action
65 -- will override any previous action that might have been registered.
66 --
67 -- Action is called before the exception is propagated to user's code.
68 -- If Action is null, this will in effect cancel all exception actions.
69
70 procedure Register_Id_Action
71 (Id : Exception_Id;
72 Action : Exception_Action);
73 -- Action will be called whenever an exception of type Id is raised. Only
74 -- one such action can be registered for each exception id, and registering
75 -- a new action will override any previous action registered for this
76 -- Exception_Id. Program_Error is raised if Id is Null_Id.
77
78 function Name_To_Id (Name : String) return Exception_Id;
79 -- Convert an exception name to an exception id. Null_Id is returned
80 -- if no such exception exists. Name must be an all upper-case string,
81 -- or the exception will not be found. The exception name must be fully
82 -- qualified (but not including Standard). It is not possible to convert
83 -- an exception that is declared within an unlabeled block.
84 --
85 -- Note: All non-predefined exceptions will return Null_Id for programs
86 -- compiled with pragma Restriction (No_Exception_Registration)
87
88 function Registered_Exceptions_Count return Natural;
89 -- Return the number of exceptions that have been registered so far.
90 -- Exceptions declared locally will not appear in this list until their
91 -- block has been executed at least once.
92 --
93 -- Note: The count includes only predefined exceptions for programs
94 -- compiled with pragma Restrictions (No_Exception_Registration).
95
96 type Exception_Id_Array is array (Natural range <>) of Exception_Id;
97
98 procedure Get_Registered_Exceptions
99 (List : out Exception_Id_Array;
100 Last : out Integer);
101 -- Return the list of registered exceptions.
102 -- Last is the index in List of the last exception returned.
103 --
104 -- An exception is registered the first time the block containing its
105 -- declaration is elaborated. Exceptions defined at library-level are
106 -- therefore immediately visible, whereas exceptions declared in local
107 -- blocks will not be visible until the block is executed at least once.
108 --
109 -- Note: The list contains only the predefined exceptions if the program
110 -- is compiled with pragma Restrictions (No_Exception_Registration);
111
112 procedure Core_Dump (Occurrence : Exception_Occurrence);
113 -- Dump memory (called a core dump in some systems) if supported by the
114 -- OS (most unix systems), and abort execution of the application. Under
115 -- Windows this procedure will not dump the memory, it will only abort
116 -- execution.
117
118 end GNAT.Exception_Actions;