[151] | 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 */ |
---|