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-2012, 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-- 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 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 52with Ada.Exceptions; use Ada.Exceptions; 53 54package 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 VMS), and abort execution of the application. 115 -- Under Windows this procedure will not dump the memory, it will only 116 -- abort execution. 117 118end GNAT.Exception_Actions; 119