1 | /*=== |
---|
2 | cexcept.h 1.0.0 (2000-Jun-21-Wed) |
---|
3 | Adam M. Costello <amc@cs.berkeley.edu> |
---|
4 | |
---|
5 | An interface for exception-handling in ANSI C, developed jointly with |
---|
6 | Cosmin Truta <cosmin@cs.toronto.edu>. |
---|
7 | |
---|
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. |
---|
15 | |
---|
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. |
---|
20 | |
---|
21 | The interface consists of one type, one well-known name, and six macros. |
---|
22 | |
---|
23 | |
---|
24 | define_exception_type(type_name); |
---|
25 | |
---|
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, |
---|
30 | or pointer. Examples: |
---|
31 | |
---|
32 | define_exception_type(int); |
---|
33 | |
---|
34 | enum exception { out_of_memory, bad_arguments, disk_full }; |
---|
35 | define_exception_type(enum exception); |
---|
36 | |
---|
37 | struct exception { int code; const char *msg; }; |
---|
38 | define_exception_type(struct exception); |
---|
39 | |
---|
40 | |
---|
41 | struct exception_context; |
---|
42 | |
---|
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. |
---|
53 | |
---|
54 | |
---|
55 | struct exception_context *the_exception_context; |
---|
56 | |
---|
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: |
---|
66 | |
---|
67 | static struct exception_context |
---|
68 | * const the_exception_context = &foo; |
---|
69 | |
---|
70 | { struct exception_context *the_exception_context = bar; ... } |
---|
71 | |
---|
72 | int blah(struct exception_context *the_exception_context, ...); |
---|
73 | |
---|
74 | extern struct exception_context the_exception_context[1]; |
---|
75 | |
---|
76 | The last example illustrates a trick that avoids creating a pointer |
---|
77 | object separate from the structure object. |
---|
78 | |
---|
79 | The name could even be a macro, for example: |
---|
80 | |
---|
81 | struct exception_context ec_array[numthreads]; |
---|
82 | #define the_exception_context (ec_array + thread_id) |
---|
83 | |
---|
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. |
---|
88 | |
---|
89 | |
---|
90 | void init_exception_context(struct exception_context *ec); |
---|
91 | |
---|
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 |
---|
100 | Try/Catch statement. |
---|
101 | |
---|
102 | |
---|
103 | Try statement |
---|
104 | Catch (expression) statement |
---|
105 | |
---|
106 | The Try/Catch/Throw macros are capitalized in order to avoid |
---|
107 | confusion with the C++ keywords, which have subtly different |
---|
108 | semantics. |
---|
109 | |
---|
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(). |
---|
119 | |
---|
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. |
---|
127 | |
---|
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: |
---|
131 | |
---|
132 | Try foo(); |
---|
133 | Catch (p[++i].e) { ... } |
---|
134 | |
---|
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. |
---|
144 | |
---|
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. |
---|
150 | |
---|
151 | |
---|
152 | Throw expression; |
---|
153 | |
---|
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. |
---|
160 | |
---|
161 | Slight limitation: If the expression is a comma-expression it must |
---|
162 | be enclosed in parentheses. |
---|
163 | |
---|
164 | |
---|
165 | Try statement |
---|
166 | Catch_anonymous statement |
---|
167 | |
---|
168 | When the value of the exception is not needed, a Try/Catch statement |
---|
169 | can use Catch_anonymous instead of Catch (expression). |
---|
170 | |
---|
171 | |
---|
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. |
---|
175 | |
---|
176 | ===*/ |
---|
177 | |
---|
178 | |
---|
179 | #ifndef CEXCEPT_H |
---|
180 | #define CEXCEPT_H |
---|
181 | |
---|
182 | |
---|
183 | #include <setjmp.h> |
---|
184 | |
---|
185 | #define define_exception_type(etype) \ |
---|
186 | struct exception__state { \ |
---|
187 | etype *exception; \ |
---|
188 | jmp_buf env; \ |
---|
189 | } |
---|
190 | |
---|
191 | struct exception_context { \ |
---|
192 | struct exception__state *last; \ |
---|
193 | int caught; \ |
---|
194 | }; |
---|
195 | |
---|
196 | #define init_exception_context(ec) ((void)((ec)->last = 0)) |
---|
197 | |
---|
198 | #define Catch(e) exception__catch(&(e)) |
---|
199 | #define Catch_anonymous exception__catch(0) |
---|
200 | |
---|
201 | #define Try \ |
---|
202 | { \ |
---|
203 | struct exception__state *exception__p, exception__s; \ |
---|
204 | int exception__i; \ |
---|
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) { \ |
---|
210 | if (&exception__s) |
---|
211 | |
---|
212 | #define exception__catch(e_addr) \ |
---|
213 | else { } \ |
---|
214 | the_exception_context->caught = 0; \ |
---|
215 | } \ |
---|
216 | else the_exception_context->caught = 1; \ |
---|
217 | the_exception_context->last = exception__p; \ |
---|
218 | break; \ |
---|
219 | } \ |
---|
220 | else exception__s.exception = e_addr; \ |
---|
221 | } \ |
---|
222 | if (!the_exception_context->caught) { } \ |
---|
223 | else |
---|
224 | |
---|
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. */ |
---|
228 | /* */ |
---|
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. */ |
---|
233 | /* */ |
---|
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. */ |
---|
237 | |
---|
238 | #define Throw \ |
---|
239 | for (;; longjmp(the_exception_context->last->env, 1)) \ |
---|
240 | if (the_exception_context->last->exception) \ |
---|
241 | *the_exception_context->last->exception = |
---|
242 | |
---|
243 | |
---|
244 | #endif /* CEXCEPT_H */ |
---|