2 cexcept.h 1.0.0 (2000-Jun-21-Wed)
3 Adam M. Costello <amc@cs.berkeley.edu>
5 An interface for exception-handling in ANSI C, developed jointly with
6 Cosmin Truta <cosmin@cs.toronto.edu>.
8 Copyright (c) 2000 Adam M. Costello and Cosmin Truta. Everyone
9 is hereby granted permission to do whatever they like with this
10 file, provided that if they modify it they take reasonable steps to
11 avoid confusing or misleading people about the authors, version,
12 and terms of use of the derived file. The copyright holders make
13 no guarantees about the correctness of this file, and are not
14 responsible for any damage resulting from its use.
16 If this interface is used by multiple .c files, they shouldn't include
17 this header file directly. Instead, create a wrapper header file that
18 includes this header file and then invokes the define_exception_type
19 macro (see below), and let your .c files include that header file.
21 The interface consists of one type, one well-known name, and six macros.
24 define_exception_type(type_name);
26 This macro is used like an external declaration. It specifies
27 the type of object that gets copied from the exception thrower to
28 the exception catcher. The type_name can be any type that can be
29 assigned to, that is, a non-constant arithmetic type, struct, union,
32 define_exception_type(int);
34 enum exception { out_of_memory, bad_arguments, disk_full };
35 define_exception_type(enum exception);
37 struct exception { int code; const char *msg; };
38 define_exception_type(struct exception);
41 struct exception_context;
43 This type may be used after the define_exception_type() macro has
44 been invoked. A struct exception_context must be known to both
45 the thrower and the catcher. It is expected that there be one
46 context for each thread that uses exceptions. It would certainly
47 be dangerous for multiple threads to access the same context.
48 One thread can use multiple contexts, but that is likely to be
49 confusing and not typically useful. The application can allocate
50 this structure in any way it pleases--automatic, static, or dynamic.
51 The application programmer should pretend not to know the structure
52 members, which are subject to change.
55 struct exception_context *the_exception_context;
57 The Try/Catch and Throw statements (described below) implicitly
58 refer to a context, using the name the_exception_context. It is
59 the application's responsibility to make sure that this name yields
60 the address of a mutable (non-constant) struct exception_context
61 wherever those statements are used. Subject to that constraint, the
62 application may declare a variable of this name anywhere it likes
63 (inside a function, in a parameter list, or externally), and may
64 use whatever storage class specifiers (static, extern, etc) or type
65 qualifiers (const, volatile) it likes. Examples:
67 static struct exception_context
68 * const the_exception_context = &foo;
70 { struct exception_context *the_exception_context = bar; ... }
72 int blah(struct exception_context *the_exception_context, ...);
74 extern struct exception_context the_exception_context[1];
76 The last example illustrates a trick that avoids creating a pointer
77 object separate from the structure object.
79 The name could even be a macro, for example:
81 struct exception_context ec_array[numthreads];
82 #define the_exception_context (ec_array + thread_id)
84 Be aware that the_exception_context is used several times by the
85 Try/Catch/Throw macros, so it shouldn't be expensive or have side
86 effects. The expansion must be a drop-in replacement for an
87 identifier, so it's safest to put parentheses around it.
90 void init_exception_context(struct exception_context *ec);
92 For context structures allocated statically (by an external
93 definition or using the "static" keyword), the implicit
94 initialization to all zeros is sufficient, but contexts allocated
95 by other means must be initialized using this macro before they
96 are used by a Try/Catch statement. It does no harm to initialize
97 a context more than once (by using this macro on a statically
98 allocated context, or using this macro twice on the same context),
99 but a context must not be re-initialized after it has been used by a
104 Catch (expression) statement
106 The Try/Catch/Throw macros are capitalized in order to avoid
107 confusion with the C++ keywords, which have subtly different
110 A Try/Catch statement has a syntax similar to an if/else
111 statement, except that the parenthesized expression goes after
112 the second keyword rather than the first. As with if/else,
113 there are two clauses, each of which may be a simple statement
114 ending with a semicolon or a brace-enclosed compound statement.
115 But whereas the else clause is optional, the Catch clause is
116 required. The expression must be a modifiable lvalue (something
117 capable of being assigned to) of the exact same type passed to
118 define_exception_type().
120 If a Throw that uses the same exception context as the Try/Catch is
121 executed within the Try clause (typically within a function called
122 by the Try clause), and the exception is not caught by a nested
123 Try/Catch statement, then a copy of the exception will be assigned
124 to the expression, and control will jump to the Catch clause. If no
125 such Throw is executed, then the assignment is not performed, and
126 the Catch clause is not executed.
128 Regardless of whether an exception is caught, the expression is
129 always evaluated exactly once, which is significant if it has side
130 effects, for example:
133 Catch (p[++i].e) { ... }
135 IMPORTANT: Jumping into or out of a Try clause (for example via
136 return, break, continue, goto, longjmp) is forbidden--the compiler
137 will not complain, but bad things will happen at run-time. Jumping
138 into or out of a Catch clause is okay, and so is jumping around
139 inside a Try clause. In many cases where one is tempted to return
140 from a Try clause, it will suffice to use Throw, and then return
141 from the Catch clause. Another option is to set a flag variable and
142 use goto to jump to the end of the Try clause, then check the flag
143 after the Try/Catch statement.
145 IMPORTANT: The values of any non-volatile automatic variables
146 changed within the Try clause are undefined after an exception is
147 caught. Therefore, variables modified inside the Try block whose
148 values are needed later outside the Try block must either use static
149 storage or be declared with the "volatile" type qualifier.
154 A Throw statement is very much like a return statement, except that
155 the expression is required. Whereas return jumps back to the place
156 where the current function was called, Throw jumps back to the Catch
157 clause of the innermost enclosing Try clause. The expression must
158 be compatible with the type passed to define_exception_type(). The
159 exception must be caught, otherwise the program may crash.
161 Slight limitation: If the expression is a comma-expression it must
162 be enclosed in parentheses.
166 Catch_anonymous statement
168 When the value of the exception is not needed, a Try/Catch statement
169 can use Catch_anonymous instead of Catch (expression).
172 Everything below this point is for the benefit of the compiler. The
173 application programmer should pretend not to know any of it, because it
174 is subject to change.
185 #define define_exception_type(etype) \
186 struct exception__state { \
191 struct exception_context { \
192 struct exception__state *last; \
196 #define init_exception_context(ec) ((void)((ec)->last = 0))
198 #define Catch(e) exception__catch(&(e))
199 #define Catch_anonymous exception__catch(0)
203 struct exception__state *exception__p, exception__s; \
205 exception__p = the_exception_context->last; \
206 the_exception_context->last = &exception__s; \
207 for (exception__i = 0; ; exception__i = 1) \
208 if (exception__i) { \
209 if (setjmp(exception__s.env) == 0) { \
212 #define exception__catch(e_addr) \
214 the_exception_context->caught = 0; \
216 else the_exception_context->caught = 1; \
217 the_exception_context->last = exception__p; \
220 else exception__s.exception = e_addr; \
222 if (!the_exception_context->caught) { } \
225 /* Try ends with if(), and Catch begins and ends with else. This */
226 /* ensures that the Try/Catch syntax is really the same as the */
227 /* if/else syntax. */
229 /* We use &exception__s instead of 1 to appease compilers that */
230 /* warn about constant expressions inside if(). Most compilers */
231 /* should still recognize that &exception__s is never zero and avoid */
232 /* generating test code. */
234 /* We use the variable exception__i to start the loop at the bottom, */
235 /* rather than jump into the loop using a switch statement, to */
236 /* appease compilers that warn about jumping into loops. */
239 for (;; longjmp(the_exception_context->last->env, 1)) \
240 if (the_exception_context->last->exception) \
241 *the_exception_context->last->exception =
244 #endif /* CEXCEPT_H */