1193279Sgabor/* GNU Objective C Runtime native exceptions 2193279Sgabor Copyright (C) 2010-2020 Free Software Foundation, Inc. 3193279Sgabor Contributed by Nicola Pero <nicola.pero@meta-innovation.com> 4193279Sgabor 5193279SgaborThis file is part of GCC. 6193279Sgabor 7193279SgaborGCC is free software; you can redistribute it and/or modify 8193279Sgaborit under the terms of the GNU General Public License as published by 9193279Sgaborthe Free Software Foundation; either version 3, or (at your option) 10193279Sgaborany later version. 11193279Sgabor 12193279SgaborGCC is distributed in the hope that it will be useful, 13193279Sgaborbut WITHOUT ANY WARRANTY; without even the implied warranty of 14193279SgaborMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15193279SgaborGNU General Public License for more details. 16193279Sgabor 17193279SgaborUnder Section 7 of GPL version 3, you are granted additional 18193279Sgaborpermissions described in the GCC Runtime Library Exception, version 19193279Sgabor3.1, as published by the Free Software Foundation. 20193279Sgabor 21193279SgaborYou should have received a copy of the GNU General Public License and 22193279Sgabora copy of the GCC Runtime Library Exception along with this program; 23193279Sgaborsee the files COPYING3 and COPYING.RUNTIME respectively. If not, see 24193279Sgabor<http://www.gnu.org/licenses/>. */ 25193279Sgabor 26193279Sgabor#ifndef __objc_exception_INCLUDE_GNU 27193279Sgabor#define __objc_exception_INCLUDE_GNU 28193279Sgabor 29193279Sgabor#include "objc.h" 30193279Sgabor#include "objc-decls.h" 31193279Sgabor 32193279Sgabor#ifdef __cplusplus 33193279Sgaborextern "C" { 34193279Sgabor#endif 35193279Sgabor 36193279Sgabor/* 'objc_exception_throw' throws the exception 'exception', which is 37193279Sgabor an exception object. 38193279Sgabor 39193279Sgabor Calls to 'objc_exception_throw' are automatically generated by the 40193279Sgabor compiler: an Objective-C "@throw exception;" statement gets 41193279Sgabor compiled into the equivalent of "objc_exception_throw 42193279Sgabor (exception);". 43193279Sgabor 44193279Sgabor 'objc_exception_throw' searches for a @catch() that can catch the 45193279Sgabor exception. By default, @catch (MyClass object) will catch all 46193279Sgabor exception objects that are of class MyClass or of a subclass of 47193279Sgabor MyClass; if the exception object is 'nil', then the exception can 48193279Sgabor only be caught with a catch-all exception handler where no 49193279Sgabor exception class is specified (such as @catch(id object)). This 50193279Sgabor behaviour can be customized by setting an 'objc_exception_matcher' 51193279Sgabor function (using objc_set_exception_matcher(), see below); if one is 52193279Sgabor set, it is used instead of the default one. 53193279Sgabor 54193279Sgabor If the exception is uncaught (there is no @catch() to catch it), 55193279Sgabor the program aborts. It is possible to customize this behaviour by 56193279Sgabor setting an 'objc_uncaught_exception_handler' function (using 57193279Sgabor objc_set_uncaught_exception_handler(), see below); if one is set, 58193279Sgabor it is executed before abort() is called. An uncaught exception 59193279Sgabor handler is expected to never return. */ 60193279Sgaborobjc_EXPORT void objc_exception_throw (id exception); 61193279Sgabor 62193279Sgabor/* Compatibility note: the Apple/NeXT runtime seems to also have 63193279Sgabor objc_exception_rethrow(), objc_begin_catch() and objc_end_catch(). 64193279Sgabor Currently the GNU runtime does not use them. */ 65193279Sgabor 66193279Sgabor/* The following functions allow customizing to a certain extent the 67193279Sgabor exception handling. They are not thread safe and should be called 68193279Sgabor during the program initialization before threads are started. They 69193279Sgabor are mostly reserved for "Foundation" libraries; in the case of 70193279Sgabor GNUstep, GNUstep Base may be using these functions to improve the 71193279Sgabor standard exception handling. You probably shouldn't use these 72193279Sgabor functions unless you are writing your own Foundation library. */ 73193279Sgabor 74193279Sgabor/* Compatibility note: objc_set_exception_preprocessor() (available on 75193279Sgabor the Apple/NeXT runtime) is not available on the GNU runtime. */ 76193279Sgabor 77193279Sgabor/* An 'objc_exception_matcher' function is used to match an exception 78193279Sgabor to a @catch clause. 'catch_class' is the class of objects caught 79193279Sgabor by the @catch clause (for example, in "@catch (Object *o)", the 80193279Sgabor catch_class is Object). It should return 1 if the exception should 81193279Sgabor be caught by a @catch with a catch_class argument, and 0 if 82193279Sgabor not. */ 83193279Sgabortypedef int (*objc_exception_matcher)(Class catch_class, id exception); 84193279Sgabor 85193279Sgabor/* Sets a new exception matcher function, and returns the previous 86193279Sgabor exception matcher function. This function is not safe to call in a 87193279Sgabor multi-threaded environment because other threads may be trying to 88193279Sgabor invoke the exception matcher while you change it! */ 89193279Sgaborobjc_EXPORT objc_exception_matcher 90193279Sgaborobjc_setExceptionMatcher (objc_exception_matcher new_matcher); 91193279Sgabor 92193279Sgabor 93193279Sgabor/* An 'objc_uncaught_exception_handler' function is a function that 94193279Sgabor handles uncaught exceptions. It should never return. */ 95193279Sgabortypedef void (*objc_uncaught_exception_handler)(id exception); 96193279Sgabor 97193279Sgabor/* Sets a new uncaught exception handler function, and returns the 98193279Sgabor previous exception handler function. This function is not safe to 99193279Sgabor call in a multi-threaded environment because other threads may be 100193279Sgabor trying to invoke the uncaught exception handler while you change 101193279Sgabor it. */ 102193279Sgaborobjc_EXPORT objc_uncaught_exception_handler 103193279Sgaborobjc_setUncaughtExceptionHandler (objc_uncaught_exception_handler new_handler); 104193279Sgabor 105193279Sgabor#ifdef __cplusplus 106193279Sgabor} 107193279Sgabor#endif 108193279Sgabor 109193279Sgabor#endif /* not __objc_exception_INCLUDE_GNU */ 110193279Sgabor