gcc/ada/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-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
  54 with Ada.Exceptions; use Ada.Exceptions;
  55
  56 package 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
 118 end GNAT.Exception_Actions;