1  /* GNU Objective C Runtime native exceptions
       2     Copyright (C) 2010-2023 Free Software Foundation, Inc.
       3     Contributed by Nicola Pero <nicola.pero@meta-innovation.com>
       4  
       5  This file is part of GCC.
       6  
       7  GCC is free software; you can redistribute it and/or modify
       8  it under the terms of the GNU General Public License as published by
       9  the Free Software Foundation; either version 3, or (at your option)
      10  any later version.
      11  
      12  GCC is distributed in the hope that it will be useful,
      13  but WITHOUT ANY WARRANTY; without even the implied warranty of
      14  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      15  GNU General Public License for more details.
      16  
      17  Under Section 7 of GPL version 3, you are granted additional
      18  permissions described in the GCC Runtime Library Exception, version
      19  3.1, as published by the Free Software Foundation.
      20  
      21  You should have received a copy of the GNU General Public License and
      22  a copy of the GCC Runtime Library Exception along with this program;
      23  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
      24  <http://www.gnu.org/licenses/>.  */
      25  
      26  #ifndef __objc_exception_INCLUDE_GNU
      27  #define __objc_exception_INCLUDE_GNU
      28  
      29  #include "objc.h"
      30  #include "objc-decls.h"
      31  
      32  #ifdef __cplusplus
      33  extern "C" {
      34  #endif
      35  
      36  /* 'objc_exception_throw' throws the exception 'exception', which is
      37     an exception object.
      38  
      39     Calls to 'objc_exception_throw' are automatically generated by the
      40     compiler: an Objective-C "@throw exception;" statement gets
      41     compiled into the equivalent of "objc_exception_throw
      42     (exception);".
      43  
      44     'objc_exception_throw' searches for a @catch() that can catch the
      45     exception.  By default, @catch (MyClass object) will catch all
      46     exception objects that are of class MyClass or of a subclass of
      47     MyClass; if the exception object is 'nil', then the exception can
      48     only be caught with a catch-all exception handler where no
      49     exception class is specified (such as @catch(id object)).  This
      50     behaviour can be customized by setting an 'objc_exception_matcher'
      51     function (using objc_set_exception_matcher(), see below); if one is
      52     set, it is used instead of the default one.
      53  
      54     If the exception is uncaught (there is no @catch() to catch it),
      55     the program aborts.  It is possible to customize this behaviour by
      56     setting an 'objc_uncaught_exception_handler' function (using
      57     objc_set_uncaught_exception_handler(), see below); if one is set,
      58     it is executed before abort() is called.  An uncaught exception
      59     handler is expected to never return.  */
      60  objc_EXPORT void objc_exception_throw (id exception);
      61  
      62  /* Compatibility note: the Apple/NeXT runtime seems to also have
      63     objc_exception_rethrow(), objc_begin_catch() and objc_end_catch().
      64     Currently the GNU runtime does not use them.  */
      65  
      66  /* The following functions allow customizing to a certain extent the
      67     exception handling.  They are not thread safe and should be called
      68     during the program initialization before threads are started.  They
      69     are mostly reserved for "Foundation" libraries; in the case of
      70     GNUstep, GNUstep Base may be using these functions to improve the
      71     standard exception handling.  You probably shouldn't use these
      72     functions unless you are writing your own Foundation library.  */
      73  
      74  /* Compatibility note: objc_set_exception_preprocessor() (available on
      75     the Apple/NeXT runtime) is not available on the GNU runtime.  */
      76  
      77  /* An 'objc_exception_matcher' function is used to match an exception
      78     to a @catch clause.  'catch_class' is the class of objects caught
      79     by the @catch clause (for example, in "@catch (Object *o)", the
      80     catch_class is Object).  It should return 1 if the exception should
      81     be caught by a @catch with a catch_class argument, and 0 if
      82     not.  */
      83  typedef int (*objc_exception_matcher)(Class catch_class, id exception);
      84  
      85  /* Sets a new exception matcher function, and returns the previous
      86     exception matcher function.  This function is not safe to call in a
      87     multi-threaded environment because other threads may be trying to
      88     invoke the exception matcher while you change it!  */
      89  objc_EXPORT objc_exception_matcher
      90  objc_setExceptionMatcher (objc_exception_matcher new_matcher);
      91  
      92  
      93  /* An 'objc_uncaught_exception_handler' function is a function that
      94     handles uncaught exceptions.  It should never return.  */
      95  typedef void (*objc_uncaught_exception_handler)(id exception);
      96  
      97  /* Sets a new uncaught exception handler function, and returns the
      98     previous exception handler function.  This function is not safe to
      99     call in a multi-threaded environment because other threads may be
     100     trying to invoke the uncaught exception handler while you change
     101     it.  */
     102  objc_EXPORT objc_uncaught_exception_handler
     103  objc_setUncaughtExceptionHandler (objc_uncaught_exception_handler new_handler);
     104  
     105  #ifdef __cplusplus
     106  }
     107  #endif
     108  
     109  #endif /* not __objc_exception_INCLUDE_GNU */