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-2003 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 2,  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.  See the GNU General Public License --
17-- for  more details.  You should have  received  a copy of the GNU General --
18-- Public License  distributed with GNAT;  see file COPYING.  If not, write --
19-- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
20-- MA 02111-1307, USA.                                                      --
21--                                                                          --
22-- As a special exception,  if other files  instantiate  generics from this --
23-- unit, or you link  this unit with other files  to produce an executable, --
24-- this  unit  does not  by itself cause  the resulting  executable  to  be --
25-- covered  by the  GNU  General  Public  License.  This exception does not --
26-- however invalidate  any other reasons why  the executable file  might be --
27-- covered by the  GNU Public License.                                      --
28--                                                                          --
29-- GNAT was originally developed  by the GNAT team at  New York University. --
30-- Extensive contributions were provided by Ada Core Technologies Inc.      --
31--                                                                          --
32------------------------------------------------------------------------------
33
34--  This package provides support for callbacks on exceptions.
35
36--  These 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 occcurs.
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
54with Ada.Exceptions; use Ada.Exceptions;
55
56package GNAT.Exception_Actions is
57
58   type Exception_Action is access
59     procedure (Occurence : 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
90   function Registered_Exceptions_Count return Natural;
91   --  Return the number of exceptions that have been registered so far.
92   --  Exceptions declared locally will not appear in this list until their
93   --  block has been executed at least once.
94   --
95   --  Note: The count includes only predefined exceptions for programs
96   --  compiled with pragma Restrictions (No_Exception_Registration).
97
98   type Exception_Id_Array is array (Natural range <>) of Exception_Id;
99
100   procedure Get_Registered_Exceptions
101     (List : out Exception_Id_Array;
102      Last : out Integer);
103   --  Return the list of registered exceptions.
104   --  Last is the index in List of the last exception returned.
105   --
106   --  An exception is registered the first time the block containing its
107   --  declaration is elaborated. Exceptions defined at library-level are
108   --  therefore immediately visible, whereas exceptions declared in local
109   --  blocks will not be visible until the block is executed at least once.
110   --
111   --  Note: The list contains only the predefined exceptions if the program
112   --  is compiled with pragma Restrictions (No_Exception_Registration);
113
114   procedure Core_Dump (Occurrence : Exception_Occurrence);
115   --  Dump memory (called a core dump in some systems), and abort execution
116   --  of the application.
117
118end GNAT.Exception_Actions;
119