Commit | Line | Data |
---|---|---|
0875b58f | 1 | /* -*-c-*- |
2 | * | |
8656dc50 | 3 | * $Id: exc.h,v 1.7 2004/04/08 01:36:11 mdw Exp $ |
0875b58f | 4 | * |
5 | * Structured exception handling in C | |
6 | * | |
7 | * (c) 1998 Straylight/Edgeware | |
8 | */ | |
9 | ||
d4efbcd9 | 10 | /*----- Licensing notice --------------------------------------------------* |
0875b58f | 11 | * |
12 | * This file is part of the mLib utilities library. | |
13 | * | |
14 | * mLib is free software; you can redistribute it and/or modify | |
c846879c | 15 | * it under the terms of the GNU Library General Public License as |
16 | * published by the Free Software Foundation; either version 2 of the | |
17 | * License, or (at your option) any later version. | |
d4efbcd9 | 18 | * |
0875b58f | 19 | * mLib is distributed in the hope that it will be useful, |
20 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
21 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
c846879c | 22 | * GNU Library General Public License for more details. |
d4efbcd9 | 23 | * |
c846879c | 24 | * You should have received a copy of the GNU Library General Public |
0bd98442 | 25 | * License along with mLib; if not, write to the Free |
26 | * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, | |
27 | * MA 02111-1307, USA. | |
0875b58f | 28 | */ |
0875b58f | 29 | |
c6e0eaf0 | 30 | #ifndef MLIB_EXC_H |
31 | #define MLIB_EXC_H | |
0875b58f | 32 | |
33 | #ifdef __cplusplus | |
34 | extern "C" { | |
35 | #endif | |
36 | ||
37 | #include <setjmp.h> | |
38 | ||
39 | /*----- Quick documentation -----------------------------------------------* | |
40 | * | |
41 | * This header file provides some exception handling facilities in C | |
42 | * programs. It modifies the syntax of the language slightly, using the | |
43 | * preprocessor. | |
44 | * | |
45 | * The `throw' expression returns no value. It has the syntax: | |
46 | * | |
47 | * THROW ( expr , expr ) | |
48 | * | |
49 | * The first expression must have type compatible with unsigned integer; it | |
50 | * identifies an `exception type'. The second must have type compatible | |
51 | * with pointer to void; it contains the `exception data'. Control is | |
52 | * passed to the current exception handler. | |
53 | * | |
54 | * The `RETHROW' expression, valid only within an exception handler, causes | |
55 | * the current exception to be thrown again. | |
56 | * | |
57 | * A `try' statement has the syntax: | |
58 | * | |
59 | * TRY stat CATCH stat END_TRY; | |
60 | * | |
61 | * The first statement is called the `test'; the second is the `handler'. | |
62 | * During execution of the test, the handler is added to a stack of | |
63 | * active exception handlers; the topmost handler on this stack is called | |
64 | * the `current' handler. When execution of the test completes, the | |
65 | * corresponding handler is removed from the stack. | |
66 | * | |
67 | * The test statement may complete in one of these ways: | |
68 | * | |
69 | * * Normal completion -- control reaches the end of the statement | |
70 | * normally. | |
71 | * | |
72 | * * Throwing an exception -- an exception is thrown when the handler is | |
73 | * the current exception handler. | |
74 | * | |
75 | * * By executing a `break' statement. | |
76 | * | |
77 | * * By executing the expression `EXIT_TRY' and transferring control to | |
78 | * a point outside the entire `try' statement (e.g., executing a `goto' | |
79 | * or `return' statement). | |
80 | * | |
81 | * Any other attempt to leave the test causes undefined behaviour. | |
82 | * | |
83 | * If an exception is thrown while the handler is the current exception | |
84 | * handler, it is given control. The variables `exc_type' and `exc_val' | |
85 | * denote the exception type and value respectively -- they are passed | |
86 | * unchanged from the `throw' expression which caused the exception. | |
87 | * A handler is deactivated before it is invoked; if it causes an | |
88 | * exception to be thrown (and does not contain a nested `try' statement) | |
89 | * control will be passed to an earlier active handler. | |
90 | * | |
91 | * Control is passed to handlers using the `longjmp' function. | |
92 | * | |
93 | * Example: | |
94 | * | |
95 | * TRY { | |
96 | * ... something dangerous ... | |
97 | * } CATCH switch (exc_type) { | |
98 | * case EXC_INTERESTING: | |
d4efbcd9 MW |
99 | * ... handle exception ... |
100 | * break; | |
0875b58f | 101 | * default: |
d4efbcd9 MW |
102 | * ... do tidying up ... |
103 | * RETHROW; | |
0875b58f | 104 | * } END_TRY; |
105 | */ | |
106 | ||
107 | /*----- Exception type allocation -----------------------------------------* | |
108 | * | |
109 | * Nobody allocates exception types, so we'll just have to try to get along | |
110 | * without too many collisions. An exception type is an unsigned long, | |
111 | * which gives us four bytes. The top two bytes identify the library which | |
112 | * `owns' the exception, with special values zero meaning `defined as part | |
113 | * of the system' and 0xFFFF providing a shared space of types which can | |
114 | * be used by anyone as long as they don't get seen by anyone else. | |
115 | * | |
116 | * The lower byte pair encodes a type number, and a value which defines | |
117 | * the type of the value field (see below). | |
118 | */ | |
119 | ||
7d40699f | 120 | /* --- Type of an exception --- */ |
0875b58f | 121 | |
122 | typedef unsigned long exc_extype; | |
123 | ||
124 | /* --- Build a byte pair from two characters --- * | |
125 | * | |
126 | * Note the icky casting to handle signed chars. | |
127 | */ | |
128 | ||
129 | #define EXC_PAIR(x, y) (((unsigned long)(unsigned char)(x) << 8) | \ | |
130 | (unsigned long)(unsigned char)(y)) | |
131 | ||
132 | /* --- Allocate an exception number --- */ | |
133 | ||
134 | #define EXC_ALLOC(owner, type) (((unsigned long)(owner) << 16) | \ | |
135 | (unsigned long)(type)) | |
136 | ||
137 | /* --- Special owner codes --- */ | |
138 | ||
139 | #define EXC_GLOBAL 0u /* The global space defined here */ | |
140 | #define EXC_SHARED 0xFFFFu /* The shared space for everyone */ | |
e1ccd441 | 141 | #define EXC_MLIB EXC_PAIR('m', 'L') /* Space for mLib exceptions */ |
0875b58f | 142 | |
143 | /*----- Exception values --------------------------------------------------* | |
144 | * | |
145 | * Exception values can have several different types. This is a mess, and | |
146 | * C doesn't handle it too well, but we can try. I'll encode the value type | |
147 | * as part of the exception type, in the top bits of the bottom byte. Messy? | |
148 | * You betcha. | |
149 | */ | |
150 | ||
151 | /* --- Encoding a value type in an extype --- */ | |
152 | ||
153 | #define EXC_TYPECODE(t, w) (((w) & ~0xC0u) | ((t) & 0xC0u)) | |
154 | ||
155 | /* --- The various value types --- */ | |
156 | ||
157 | #define EXC_NOVAL 0x00u /* No interesting value */ | |
158 | #define EXC_INTVAL 0x40u /* Integer value */ | |
159 | #define EXC_PTRVAL 0x80u /* Arbitrary pointer value */ | |
160 | #define EXC_STRVAL 0xC0u /* Pointer to character string */ | |
161 | ||
162 | /* --- Allocating exceptions with appropriate types --- */ | |
163 | ||
164 | #define EXC_ALLOCN(o, t) EXC_TYPECODE(EXC_NOVAL, EXC_ALLOC(o, t)) | |
165 | #define EXC_ALLOCI(o, t) EXC_TYPECODE(EXC_INTVAL, EXC_ALLOC(o, t)) | |
166 | #define EXC_ALLOCP(o, t) EXC_TYPECODE(EXC_PTRVAL, EXC_ALLOC(o, t)) | |
167 | #define EXC_ALLOCS(o, t) EXC_TYPECODE(EXC_STRVAL, EXC_ALLOC(o, t)) | |
168 | ||
169 | /* --- A union representing the type --- */ | |
170 | ||
171 | typedef union exc_exval { | |
172 | int i; | |
173 | void *p; | |
174 | char *s; | |
175 | } exc_exval; | |
176 | ||
177 | /*----- Predefined exceptions ---------------------------------------------*/ | |
178 | ||
179 | /* --- @EXC_NOMEM@ --- * | |
180 | * | |
181 | * Value: --- | |
182 | * | |
183 | * Meaning: An attempt to allocate memory failed. | |
184 | */ | |
185 | ||
186 | #define EXC_NOMEM EXC_ALLOCN(EXC_GLOBAL, 0u) | |
187 | ||
188 | /* --- @EXC_ERRNO@ --- * | |
189 | * | |
190 | * Value: @int errno@ = the error raised | |
191 | * | |
192 | * Meaning: Some kind of OS error occurred. | |
193 | */ | |
194 | ||
195 | #define EXC_ERRNO EXC_ALLOCI(EXC_GLOBAL, 1u) | |
196 | ||
197 | /* --- @EXC_OSERROR@ --- * | |
198 | * | |
199 | * Value: @os_error *e@ = pointer to error block | |
200 | * | |
201 | * Meaning: For RISC OS programmers only: alternative way of propagating | |
202 | * errors. | |
203 | */ | |
204 | ||
205 | #define EXC_OSERROR EXC_ALLOCP(EXC_GLOBAL, 1u) | |
206 | ||
207 | /* --- @EXC_SIGNAL@ --- * | |
208 | * | |
209 | * Value: @int sig@ = signal number | |
210 | * | |
211 | * Meaning: Report the raising of a signal. | |
212 | */ | |
213 | ||
214 | #define EXC_SIGNAL EXC_ALLOCI(EXC_GLOBAL, 2u) | |
215 | ||
216 | /* --- @EXC_FAIL@ --- * | |
217 | * | |
218 | * Value: @const char *p@ = pointer to expanatory string | |
219 | * | |
220 | * Meaning: Miscellaneous error. | |
221 | */ | |
222 | ||
223 | #define EXC_FAIL EXC_ALLOCS(EXC_GLOBAL, 0xFFu) | |
224 | ||
225 | /*----- An exception handler block ----------------------------------------*/ | |
226 | ||
227 | /* --- Try to think of this as being opaque --- */ | |
228 | ||
229 | typedef struct __exc_hnd { | |
230 | struct __exc_hnd *next; /* Pointer to next record down */ | |
231 | exc_extype type; /* Type of this exception */ | |
232 | exc_exval val; /* Value of this exception */ | |
233 | jmp_buf buf; /* Jump buffer when exceptions hit */ | |
234 | } __exc_hnd; | |
235 | ||
236 | /*----- Global variables --------------------------------------------------*/ | |
237 | ||
238 | extern __exc_hnd *__exc_list; /* List of active handlers */ | |
239 | ||
240 | /*----- Macros ------------------------------------------------------------*/ | |
241 | ||
242 | /* --- References to current exception type and value --- */ | |
243 | ||
244 | #define exc_type (__exc_ec.type) | |
245 | #define exc_val (__exc_ec.val) | |
246 | #define exc_i (__exc_ec.val.i) | |
247 | #define exc_p (__exc_ec.val.p) | |
248 | #define exc_s (__exc_ec.val.s) | |
249 | ||
250 | /* --- How it actually works --- * | |
251 | * | |
252 | * A `try' block is contained within a block which provides an exception | |
253 | * handler buffer in automatic storage. This block is a loop, to allow | |
254 | * `break' to escape from it. It adds the handler buffer to the top of a | |
255 | * list, and does a `setjmp' to allow a return here following an exception. | |
256 | * The `setjmp' returns zero for the `try' section, and nonzero if there's | |
257 | * an exception to `catch'. It looks a little like this: | |
258 | * | |
259 | * do { | |
260 | * __exc_hnd h; | |
261 | * add_handler(&h); | |
262 | * if (!setjmp(h.buf)) { | |
d4efbcd9 MW |
263 | * do <try code> while (0); |
264 | * remove_handler(&h); | |
0875b58f | 265 | * } else |
d4efbcd9 | 266 | * <catch code> |
0875b58f | 267 | * } while (0) |
268 | * | |
269 | * Everything else is ugly hacking to make things work. | |
270 | */ | |
271 | ||
272 | /* --- Trying things which may cause exceptions --- */ | |
273 | ||
274 | #define TRY do { \ | |
275 | volatile __exc_hnd __exc_ec; \ | |
276 | __exc_ec.next = __exc_list; \ | |
277 | __exc_list = (__exc_hnd *)&__exc_ec; \ | |
278 | if (!setjmp(*(jmp_buf *)&__exc_ec.buf /* very nasty! */ )) { do | |
279 | ||
280 | #define EXIT_TRY do __exc_list = __exc_ec.next; while (0) | |
281 | #define CATCH while (0); EXIT_TRY; } else | |
282 | ||
283 | #define END_TRY } while (0) | |
284 | ||
285 | /* --- Raising exceptions --- */ | |
286 | ||
287 | #define THROW __exc_throw | |
288 | #define RETHROW __exc_rethrow(__exc_ec.type, __exc_ec.val) | |
289 | ||
290 | /*----- Functions ---------------------------------------------------------*/ | |
291 | ||
292 | /* --- @exc_uncaught@ --- * | |
293 | * | |
294 | * Arguments: @void (*proc)(exc_extype type, exc_exval val) = new handler | |
295 | * | |
296 | * Returns: Pointer to the old handler value. | |
297 | * | |
298 | * Use: Sets the handler for uncaught exceptions. | |
299 | */ | |
300 | ||
301 | typedef void (*exc__uncaught)(exc_extype /*type*/, exc_exval /*val*/); | |
302 | extern exc__uncaught exc_uncaught(exc__uncaught /*proc*/); | |
303 | ||
304 | /* --- @__exc_throw@ --- * | |
305 | * | |
306 | * Arguments: @exc_extype type@ = type of exception to throw | |
307 | * | |
308 | * Returns: Doesn't | |
309 | * | |
310 | * Use: NOT FOR USER CONSUMPTION. Reads an appropriate exception | |
311 | * value and throws an exception. | |
312 | */ | |
313 | ||
314 | extern void __exc_throw(exc_extype /*type*/, ...); | |
315 | ||
316 | /* --- @__exc_rethrow@ --- * | |
317 | * | |
318 | * Arguments: @exc_extype type@ = type of exception to throw | |
319 | * @exc_exval val@ = value of exception to throw | |
320 | * | |
321 | * Returns: Doesn't | |
322 | * | |
323 | * Use: NOT FOR USER CONSUMPTION. Does the donkey-work of raising | |
324 | * an exception. | |
325 | */ | |
326 | ||
327 | extern void __exc_rethrow(exc_extype /*type*/, exc_exval /*val*/); | |
328 | ||
329 | /*----- That's all, folks -------------------------------------------------*/ | |
330 | ||
331 | #ifdef __cplusplus | |
332 | } | |
333 | #endif | |
334 | ||
335 | #endif |