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