libobjc/objc/objc-exception.h

   1 /* GNU Objective C Runtime native exceptions
   2    Copyright (C) 2010 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/objc.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /* 'objc_exception_throw' throws the exception 'exception', which is
  36    an exception object.
  37
  38    Calls to 'objc_exception_throw' are automatically generated by the
  39    compiler: an Objective-C "@throw exception;" statement gets
  40    compiled into the equivalent of "objc_exception_throw
  41    (exception);".
  42
  43    'objc_exception_throw' searches for a @catch() that can catch the
  44    exception.  By default, @catch (MyClass object) will catch all
  45    exception objects that are of class MyClass or of a subclass of
  46    MyClass; if the exception object is 'nil', then the exception can
  47    only be caught with a catch-all exception handler where no
  48    exception class is specified (such as @catch(id object)).  This
  49    behaviour can be customized by setting an 'objc_exception_matcher'
  50    function (using objc_set_exception_matcher(), see below); if one is
  51    set, it is used instead of the default one.
  52
  53    If the exception is uncaught (there is no @catch() to catch it),
  54    the program aborts.  It is possible to customize this behaviour by
  55    setting an 'objc_uncaught_exception_handler' function (using
  56    objc_set_uncaught_exception_handler(), see below); if one is set,
  57    it is executed before abort() is called.  An uncaught exception
  58    handler is expected to never return.
  59  */
  60 void objc_exception_throw (id exception);
  61
  62 /* PS: the Apple runtime seems to also have objc_exception_rethrow(),
  63    objc_begin_catch() and objc_end_catch().  Currently the GNU runtime
  64    does not use them.
  65 */
  66
  67 /* The following functions allow customizing to a certain extent the
  68    exception handling.  They are not thread safe and should be called
  69    during the program initialization before threads are started.  They
  70    are mostly reserved for "Foundation" libraries; in the case of
  71    GNUstep, gnustep-base may be using these functions to improve the
  72    standard exception handling.  You probably shouldn't use these
  73    functions unless you are writing your own Foundation library.
  74 */
  75
  76 /* PS: objc_set_exception_preprocessor() (available on the Apple
  77    runtime) is not supported on the GNU runtime.  */
  78
  79 /* An 'objc_exception_matcher' function is used to match an exception
  80    to a @catch clause.  'catch_class' is the class of objects caught
  81    by the @catch clause (for example, in "@catch (Object *o)", the
  82    catch_class is Object).  It should return 1 if the exception should
  83    be caught by a @catch with a catch_class argument, and 0 if
  84    not.  */
  85 typedef int (*objc_exception_matcher)(Class catch_class, id exception);
  86
  87 /* Sets a new exception matcher function, and returns the previous
  88    exception matcher function.  This function is not safe to call in a
  89    multi-threaded environment because other threads may be trying to
  90    invoke the exception matcher while you change it!  */
  91 objc_exception_matcher
  92 objc_set_exception_matcher (objc_exception_matcher new_matcher);
  93
  94
  95 /* An 'objc_uncaught_exception_handler' function is a function that
  96    handles uncaught exceptions.  It should never return.  */
  97 typedef void (*objc_uncaught_exception_handler)(id exception);
  98
  99 /* Sets a new uncaught exception handler function, and returns the
 100    previous exception handler function.  This function is not safe to
 101    call in a multi-threaded environment because other threads may be
 102    trying to invoke the uncaught exception handler while you change
 103    it.
 104 */
 105 objc_uncaught_exception_handler
 106 objc_set_uncaught_exception_handler (objc_uncaught_exception_handler new_handler);
 107
 108
 109 /* For compatibility with the Apple runtime.  */
 110 #define objc_setExceptionMatcher objc_set_exception_matcher
 111 #define objc_setUncaughtExceptionHandler objc_set_uncaught_exception_handler
 112
 113 #ifdef __cplusplus
 114 }
 115 #endif
 116
 117 #endif /* not __objc_exception_INCLUDE_GNU */