Debian Codegraph @

podofo/3rdparty/adobe/afdko/include/supportexcept.h

raw
1 /* Copyright 2014 Adobe Systems Incorporated (http://www.adobe.com/). All Rights Reserved.
2 This software is licensed as OpenSource, under the Apache License, Version 2.0.
3 This license is available at: http://opensource.org/licenses/Apache-2.0. */
4
5 /*
6 except.h
7 */
8
9 /* exception handling */
10
11 #ifndef EXCEPT_H
12 #define EXCEPT_H
13
14 #ifndef WINATM
15 #define WINATM 0
16 #endif
17
18 #include "supportenvironment.h"
19 #include "supportpublictypes.h"
20 #if OS == os_mach
21 #include "supportossyslib.h"
22 #elif !WINATM
23 #include <stdlib.h>
24 #endif
25 /* #include CANTHAPPEN */ /* To include Abort processing, by reference */
26
27 #if defined(USE_CXX_EXCEPTION) && !defined(__cplusplus)
28 #error("must be compiled as C++ to use C++ exception as error handling")
29 #endif
30
31 #ifndef USE_CXX_EXCEPTION
32 /* If the macro setjmp_h is defined, it is the #include path to be used
33 instead of <setjmp.h>
34 */
35 #ifdef setjmp_h
36 #include setjmp_h
37 #else /* setjmp_h */
38 #ifdef VAXC
39 #include setjmp
40 #else /* VAXC */
41 #include <setjmp.h>
42 #endif /* VAXC */
43 #endif /* setjmp_h */
44 #endif
45
46 /*
47 This interface defines a machine-independent exception handling
48 facility. It depends only on the availability of setjmp and longjmp.
49 Note that we depend on native setjmp and longjmp facilities; it's
50 not possible to interpose a veneer due to the way setjmp works.
51 (In fact, in ANSI C, setjmp is a macro, not a procedure.)
52
53 The exception handler is largely defined by a collection of macros
54 that provide some additional "syntax". A stretch of code that needs
55 to handle exceptions is written thus:
56
57 DURING
58 statement1;
59 statement2;
60 ...
61 HANDLER
62 statement3
63 statement4;
64 ...
65 END_HANDLER
66
67 The meaning of this is as follows. Normally, the statements between
68 DURING and HANDLER are executed. If no exception occurs, the statements
69 between HANDLER and END_HANDLER are bypassed; execution resumes at the
70 statement after END_HANDLER.
71
72 If an exception is raised while executing the statements between
73 DURING and HANDLER (including any procedure called from those statements),
74 execution of those statements is aborted and control passes to the
75 statements between HANDLER and END_HANDLER. These statements
76 comprise the "exception handler" for exceptions occurring between
77 the DURING and the HANDLER.
78
79 The exception handler has available to it two local variables,
80 Exception.Code and Exception.Message, which are the values passed
81 to the call to RAISE that generated the exception (see below).
82 These variables have valid contents only between HANDLER and
83 END_HANDLER.
84
85 If the exception handler simply falls off the end (or returns, or
86 whatever), propagation of the exception ceases. However, if the
87 exception handler executes RERAISE, the exception is propagated to
88 the next outer dynamically enclosing occurrence of DURING ... HANDLER.
89
90 There are two usual reasons for wanting to handle exceptions:
91
92 1. To clean up any local state (e.g., deallocate dynamically allocated
93 storage), then allow the exception to propagate further. In this
94 case, the handler should perform its cleanup, then execute RERAISE.
95
96 2. To recover from certain exceptions that might occur, then continue
97 normal execution. In this case, the handler should perform a
98 "switch" on Exception.Code to determine whether the exception
99 is one it is prepared to recover from. If so, it should perform
100 the recovery and just fall through; if not, it should execute
101 RERAISE to propagate the exception to a higher-level handler.
102
103 Note that in an environment with multiple contexts (i.e., multiple
104 coroutines), each context has its own stack of nested exception
105 handlers. An exception is raised within the currently executing
106 context and transfers control to a handler in the same context; the
107 exception does not propagate across context boundaries.
108
109 CAUTIONS:
110
111 Due to multi-threading concerns, a global chain of exception buffers
112 have been removed from DURING ... HANDLER implementation when setjmp/longjmp
113 is selected as the exception handling mechanism.
114 Instead, at least one, usually the outer-most exception handler must be
115 declared with DURING_EX instead of DURING, and its env parameter is respected when
116 longjmp is used as the exception thrown mechanism under C or USE_CXX_EXCEPTION undefined.
117 Handlers within HANDLER ... END_HANDLER following DURING (not DURING_EX) are simply ignored.
118 When C++ exception is used as the implementation, all handlers are respected.
119
120 The state of local variables at the time the HANDLER is invoked may
121 be unpredictable. In particular, a local variable that is modified
122 between DURING and HANDLER has an unpredictable value between
123 HANDLER and END_HANDLER. However, a local variable that is set before
124 DURING and not modified between DURING and HANDLER has a predictable
125 value.
126 */
127
128 /* Data structures */
129
130 typedef struct _t_Exc_buf {
131 #ifdef USE_CXX_EXCEPTION
132 _t_Exc_buf(int code = 0, char *msg = 0) : Message(msg), Code(code) {}
133 #else
134 jmp_buf Environ; /* saved environment */
135 #endif
136 char *Message; /* Human-readable cause */
137 int Code; /* Exception code */
138 } _Exc_Buf;
139
140 /* Macros defining the exception handler "syntax":
141 DURING statements HANDLER statements END_HANDLER
142 (see the description above)
143 */
144
145 #ifdef USE_CXX_EXCEPTION
146 #define DURING_EX(env) DURING
147 #define DURING \
148 { \
149 _Exc_Buf Exception; \
150 try {
151 #define HANDLER \
152 } \
153 catch (_Exc_Buf & e) { \
154 Exception = e;
155
156 #define END_HANDLER \
157 } \
158 }
159
160 #else /* USE_CXX_EXCEPTION */
161 #define DURING_EX(env) \
162 { \
163 _Exc_Buf Exception; \
164 _Exc_Buf *_EBP = &env; \
165 if (!setjmp(env.Environ)) {
166 #define DURING \
167 { \
168 _Exc_Buf Exception; \
169 _Exc_Buf *_EBP = &Exception; \
170 Exception.Code = 0; \
171 if (1) {
172 #define HANDLER \
173 } \
174 else { \
175 Exception.Code = _EBP->Code; \
176 Exception.Message = NULL;
177
178 #define END_HANDLER \
179 } \
180 }
181
182 #endif /* USE_CXX_EXCEPTION */
183
184 /* Exported Procedures */
185
186 extern procedure os_raise(_Exc_Buf *buf, int Code, char *Message);
187 /* Initiates an exception; always called via the RAISE macro.
188 This procedure never returns; instead, the stack is unwound and
189 control passes to the beginning of the exception handler statements
190 for the innermost dynamically enclosing occurrence of
191 DURING ... HANDLER. The Code and Message arguments are passed to
192 that handler as described above.
193
194 It is legal to call os_raise from within a "signal" handler for a
195 synchronous event such as floating point overflow. It is not reasonable
196 to do so from within a "signal" handler for an asynchronous event
197 (e.g., interrupt), since the exception handler's data structures
198 are not updated atomically with respect to asynchronous events.
199
200 If there is no dynamically enclosing exception handler, os_raise
201 writes an error message to os_stderr and aborts with CantHappen.
202 */
203
204 #if !defined(USE_CXX_EXCEPTION) && !WINATM && OS != os_windowsNT
205 #ifndef setjmp
206 extern int setjmp(jmp_buf buf);
207 #endif
208 /* Saves the caller's environment in the buffer (which is an array
209 type and therefore passed by pointer), then returns the value zero.
210 It may return again if longjmp is executed subsequently (see below).
211 */
212
213 /*extern _CRTIMP procedure CDECL longjmp (jmp_buf buf, int value);*/
214 /* Restores the environment saved by an earlier call to setjmp,
215 unwinding the stack and causing setjmp to return again with
216 value as its return value (which must be non-zero).
217 The procedure that called setjmp must not have returned or
218 otherwise terminated. The saved environment must be at an earlier
219 place on the same stack as the call to longjmp (in other words,
220 it must not be in a different coroutine). It is legal to call
221 longjmp in a signal handler and to restore an environment
222 outside the signal handler; longjmp must be able to unwind
223 the signal cleanly in such a case.
224 */
225
226 #endif /* !WINATM */
227
228 /* In-line Procedures */
229
230 #define RAISE os_raise
231 /* See os_raise above; defined as a macro simply for consistency */
232
233 #define RERAISE RAISE(&Exception, Exception.Code, Exception.Message)
234 /* Called from within an exception handler (between HANDLER and
235 END_HANDLER), propagates the same exception to the next outer
236 dynamically enclosing exception handler; does not return.
237 */
238
239 #define ecComponentPrivBase 256
240 /* Error codes 256-511 are reserved for any component of the system
241 to use as it wishes with the restriction that all procedures on
242 the stack must be procedures from within the component when one
243 of these errors is raised. These errors are for the private use of
244 the component and should never be seen by procedures outside the
245 component.
246 */
247
248 #endif /* EXCEPT_H */