]>
Commit | Line | Data |
---|---|---|
e30511ed | 1 | /* GNU Objective C Runtime native exceptions |
83ffe9cd | 2 | Copyright (C) 2010-2023 Free Software Foundation, Inc. |
e30511ed NP |
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 | ||
e976a775 | 29 | #include "objc.h" |
805a07f1 | 30 | #include "objc-decls.h" |
e30511ed NP |
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 | |
805a07f1 NP |
59 | handler is expected to never return. */ |
60 | objc_EXPORT void objc_exception_throw (id exception); | |
e30511ed | 61 | |
3d0d8739 NP |
62 | /* Compatibility note: the Apple/NeXT runtime seems to also have |
63 | objc_exception_rethrow(), objc_begin_catch() and objc_end_catch(). | |
805a07f1 | 64 | Currently the GNU runtime does not use them. */ |
e30511ed NP |
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 | |
e976a775 | 70 | GNUstep, GNUstep Base may be using these functions to improve the |
e30511ed | 71 | standard exception handling. You probably shouldn't use these |
805a07f1 | 72 | functions unless you are writing your own Foundation library. */ |
e30511ed | 73 | |
3d0d8739 NP |
74 | /* Compatibility note: objc_set_exception_preprocessor() (available on |
75 | the Apple/NeXT runtime) is not available on the GNU runtime. */ | |
e30511ed NP |
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! */ | |
805a07f1 | 89 | objc_EXPORT objc_exception_matcher |
2461ab4b | 90 | objc_setExceptionMatcher (objc_exception_matcher new_matcher); |
e30511ed NP |
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 | |
805a07f1 NP |
101 | it. */ |
102 | objc_EXPORT objc_uncaught_exception_handler | |
2461ab4b | 103 | objc_setUncaughtExceptionHandler (objc_uncaught_exception_handler new_handler); |
e30511ed NP |
104 | |
105 | #ifdef __cplusplus | |
106 | } | |
107 | #endif | |
108 | ||
109 | #endif /* not __objc_exception_INCLUDE_GNU */ |