1/* GNU Objective C Runtime native exceptions
2   Copyright (C) 2010-2020 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