gcc/ada/libgnat/g-moreex.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT LIBRARY COMPONENTS                          --
   4 --                                                                          --
   5 --            G N A T . M O S T _ R E C E N T _ E X C E P T I O N           --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --                     Copyright (C) 2000-2020, AdaCore                     --
  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 routines for accessing the most recently raised
  33 --  exception. This may be useful for certain logging activities. It may
  34 --  also be useful for mimicking implementation dependent capabilities in
  35 --  Ada 83 compilers, but see also GNAT.Current_Exceptions for this usage.
  36
  37 with Ada.Exceptions;
  38 package GNAT.Most_Recent_Exception is
  39
  40    -----------------
  41    -- Subprograms --
  42    -----------------
  43
  44    function Occurrence
  45      return Ada.Exceptions.Exception_Occurrence;
  46    --  Returns the Exception_Occurrence for the most recently raised exception
  47    --  in the current task. If no exception has been raised in the current task
  48    --  prior to the call, returns Null_Occurrence.
  49
  50    function Occurrence_Access
  51      return Ada.Exceptions.Exception_Occurrence_Access;
  52    --  Similar to the above, but returns an access to the occurrence value.
  53    --  This value is in a task specific location, and may be validly accessed
  54    --  as long as no further exception is raised in the calling task.
  55
  56    --  Note: unlike the routines in GNAT.Current_Exception, these functions
  57    --  access the most recently raised exception, regardless of where they
  58    --  are called. Consider the following example:
  59
  60    --     exception
  61    --        when Constraint_Error =>
  62    --          begin
  63    --             ...
  64    --          exception
  65    --             when Tasking_Error => ...
  66    --          end;
  67    --
  68    --          --  Assuming a Tasking_Error was raised in the inner block,
  69    --          --  a call to GNAT.Most_Recent_Exception.Occurrence will
  70    --          --  return information about this Tasking_Error exception,
  71    --          --  not about the Constraint_Error exception being handled
  72    --          --  by the current handler code.
  73
  74 end GNAT.Most_Recent_Exception;