1/* GNU Objective C Runtime native exceptions 2 Copyright (C) 2010-2022 Free Software Foundation, Inc. 3 Contributed by Nicola Pero <nicola.pero@meta-innovation.com> 4 5This file is part of GCC. 6 7GCC is free software; you can redistribute it and/or modify 8it under the terms of the GNU General Public License as published by 9the Free Software Foundation; either version 3, or (at your option) 10any later version. 11 12GCC is distributed in the hope that it will be useful, 13but WITHOUT ANY WARRANTY; without even the implied warranty of 14MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15GNU General Public License for more details. 16 17Under Section 7 of GPL version 3, you are granted additional 18permissions described in the GCC Runtime Library Exception, version 193.1, as published by the Free Software Foundation. 20 21You should have received a copy of the GNU General Public License and 22a copy of the GCC Runtime Library Exception along with this program; 23see 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 33extern "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. */ 60objc_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. */ 83typedef 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! */ 89objc_EXPORT objc_exception_matcher 90objc_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. */ 95typedef 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. */ 102objc_EXPORT objc_uncaught_exception_handler 103objc_setUncaughtExceptionHandler (objc_uncaught_exception_handler new_handler); 104 105#ifdef __cplusplus 106} 107#endif 108 109#endif /* not __objc_exception_INCLUDE_GNU */ 110