3 /* ex - Exception Handling (modified to fit into SimGrid from OSSP version) */
5 /* Copyright (c) 2005-2006 Martin Quinson */
6 /* Copyright (c) 2002-2004 Ralf S. Engelschall <rse@engelschall.com> */
7 /* Copyright (c) 2002-2004 The OSSP Project <http://www.ossp.org/> */
8 /* Copyright (c) 2002-2004 Cable & Wireless <http://www.cw.com/> */
9 /* All rights reserved. */
11 /* This program is free software; you can redistribute it and/or modify it
12 * under the terms of the license (GNU LGPL) which comes with this package. */
17 #include "xbt/sysdep.h"
19 #include "xbt/virtu.h"
21 /* do not include execinfo.h directly since it's not always available.
22 Instead, copy the parts we need (and fake when it's not there) */
23 XBT_PUBLIC(int) backtrace (void **__array, int __size);
26 /*-*-* Emergency debuging: define this when the exceptions get crazy *-*-*/
33 # define MAYDAY_SAVE(m) printf("%d %s:%d save %p\n", \
34 (*xbt_getpid)(),__FILE__,__LINE__, \
37 # define MAYDAY_RESTORE(m) printf("%d %s:%d restore %p\n", \
38 (*xbt_getpid)(),__FILE__,__LINE__, \
41 # define MAYDAY_CATCH(e) printf("%d %s:%d Catched '%s'\n", \
42 (*xbt_getpid)(),__FILE__,__LINE__, \
46 # define MAYDAY_SAVE(m)
47 # define MAYDAY_RESTORE(m)
48 # define MAYDAY_CATCH(e)
51 /*-*-* end of debugging stuff *-*-*/
53 #if defined(__EX_MCTX_MCSC__)
54 #include <ucontext.h> /* POSIX.1 ucontext(3) */
55 #define __ex_mctx_struct ucontext_t uc;
56 #define __ex_mctx_save(mctx) (getcontext(&(mctx)->uc) == 0)
57 #define __ex_mctx_restored(mctx) /* noop */
58 #define __ex_mctx_restore(mctx) (void)setcontext(&(mctx)->uc)
60 #elif defined(__EX_MCTX_SSJLJ__)
61 #include <setjmp.h> /* POSIX.1 sigjmp_buf(3) */
62 #define __ex_mctx_struct sigjmp_buf jb;
63 #define __ex_mctx_save(mctx) (sigsetjmp((mctx)->jb, 1) == 0)
64 #define __ex_mctx_restored(mctx) /* noop */
65 #define __ex_mctx_restore(mctx) (void)siglongjmp((mctx)->jb, 1)
67 #elif defined(__EX_MCTX_SJLJ__) || !defined(__EX_MCTX_CUSTOM__) || defined(__EX_MAYDAY)
68 #include <setjmp.h> /* ISO-C jmp_buf(3) */
69 #define __ex_mctx_struct jmp_buf jb;
70 #define __ex_mctx_save(mctx) ( MAYDAY_SAVE(mctx) setjmp((mctx)->jb) == 0)
71 #define __ex_mctx_restored(mctx) /* noop */
72 #define __ex_mctx_restore(mctx) ( MAYDAY_RESTORE(mctx) (void)longjmp((mctx)->jb, 1))
75 /* declare the machine context type */
76 typedef struct { __ex_mctx_struct } __ex_mctx_t;
78 /** @addtogroup XBT_ex
79 * @brief A set of macros providing exception a la C++ in ANSI C (grounding feature)
81 * This module is a small ISO-C++ style exception handling library
82 * for use in the ISO-C language. It allows you to use the paradigm
83 * of throwing and catching exceptions in order to reduce the amount
84 * of error handling code without hindering program robustness.
86 * This is achieved by directly transferring exceptional return codes
87 * (and the program control flow) from the location where the exception
88 * is raised (throw point) to the location where it is handled (catch
89 * point) -- usually from a deeply nested sub-routine to a parent
90 * routine. All intermediate routines no longer have to make sure that
91 * the exceptional return codes from sub-routines are correctly passed
94 * These features are brought to you by a modified version of the libex
95 * library, one of the numerous masterpiece of Ralf S. Engelschall.
97 * \htmlonly <div class="toc">\endhtmlonly
99 * @section XBT_ex_toc TABLE OF CONTENTS
101 * - \ref XBT_ex_intro
103 * - \ref XBT_ex_pitfalls
105 * \htmlonly </div> \endhtmlonly
107 * @section XBT_ex_intro DESCRIPTION
109 * In SimGrid, an exception is a triple <\a msg , \a category , \a value>
110 * where \a msg is a human-readable text describing the exceptional
111 * condition, \a code an integer describing what went wrong and \a value
112 * providing a sort of sub-category. (this is different in the original libex).
114 * @section XBT_ex_base BASIC USAGE
116 * \em TRY \b TRIED_BLOCK [\em CLEANUP \b CLEANUP_BLOCK] \em CATCH (variable) \b CATCH_BLOCK
118 * This is the primary syntactical construct provided. It is modeled after the
119 * ISO-C++ try-catch clause and should sound familiar to most of you.
121 * Any exception thrown directly from the TRIED_BLOCK block or from called
122 * subroutines is caught. Cleanups which must be done after this block
123 * (whenever an exception arised or not) should be placed into the optionnal
124 * CLEANUP_BLOCK. The code dealing with the exceptions when they arise should
125 * be placed into the (mandatory) CATCH_BLOCK.
128 * In absence of exception, the control flow goes into the blocks TRIED_BLOCK
129 * and CLEANUP_BLOCK (if present); The CATCH_BLOCK block is then ignored.
131 * When an exception is thrown, the control flow goes through the following
132 * blocks: TRIED_BLOCK (up to the statement throwing the exception),
133 * CLEANUP_BLOCK (if any) and CATCH_BLOCK. The exception is stored in a
134 * variable for inspection inside the CATCH_BLOCK. This variable must be
135 * declared in the outter scope, but its value is only valid within the
139 * - TRY, CLEANUP and CATCH cannot be used separately, they work
140 * only in combination and form a language clause as a whole.
141 * - In contrast to the syntax of other languages (such as C++ or Jave) there
142 * is only one CATCH block and not multiple ones (all exceptions are
143 * of the same \em xbt_ex_t C type).
144 * - the variable of CATCH can naturally be reused in subsequent
146 * - it is possible to nest TRY clauses.
148 * The TRY block is a regular ISO-C language statement block, but
150 * <center><b>it is not
151 * allowed to jump into it via "goto" or longjmp(3) or out of it via "break",
152 * "return", "goto" or longjmp(3)</b>.</center>
154 * This is because there is some hidden setup and
155 * cleanup that needs to be done regardless of whether an exception is
156 * caught. Bypassing these steps will break the exception handling facility.
157 * The symptom are likely to be a segfault at the next exception raising point,
158 * ie far away from the point where you did the mistake. If you suspect
159 * that kind of error in your code, have a look at the little script
160 * <tt>tools/xbt_exception_checker</tt> in the CVS. It extracts all the TRY
161 * blocks from a set of C files you give it and display them (and only
162 * them) on the standard output. You can then grep for the forbidden
163 * keywords on that output.
165 * The CLEANUP and CATCH blocks are regular ISO-C language statement
166 * blocks without any restrictions. You are even allowed to throw (and, in the
167 * CATCH block, to re-throw) exceptions.
169 * There is one subtle detail you should remember about TRY blocks:
170 * Variables used in the CLEANUP or CATCH clauses must be declared with
171 * the storage class "volatile", otherwise they might contain outdated
172 * information if an exception is thrown.
175 * This is because you usually do not know which commands in the TRY
176 * were already successful before the exception was thrown (logically speaking)
177 * and because the underlying ISO-C setjmp(3) facility applies those
178 * restrictions (technically speaking). As a matter of fact, value changes
179 * between the TRY and the THROW may be discarded if you forget the
180 * "volatile" keyword.
182 * \section XBT_ex_pitfalls PROGRAMMING PITFALLS
184 * Exception handling is a very elegant and efficient way of dealing with
185 * exceptional situation. Nevertheless it requires additional discipline in
186 * programming and there are a few pitfalls one must be aware of. Look the
187 * following code which shows some pitfalls and contains many errors (assuming
188 * a mallocex() function which throws an exception if malloc(3) fails):
192 * \until end_of_bad_example
194 * This example raises a few issues:
195 * -# \b variable \b scope \n
196 * Variables which are used in the CLEANUP or CATCH clauses must be
197 * declared before the TRY clause, otherwise they only exist inside the
198 * TRY block. In the example above, cp1, cp2 and cp3 only exist in the
199 * TRY block and are invisible from the CLEANUP and CATCH
201 * -# \b variable \b initialization \n
202 * Variables which are used in the CLEANUP or CATCH clauses must
203 * be initialized before the point of the first possible THROW is
204 * reached. In the example above, CLEANUP would have trouble using cp3
205 * if mallocex() throws a exception when allocating a TOOBIG buffer.
206 * -# \b volatile \b variable \n
207 * Variables which are used in the CLEANUP or CATCH clauses MUST BE
208 * DECLARED AS "volatile", otherwise they might contain outdated
209 * information when an exception is thrown.
210 * -# \b clean \b before \b catch \n
211 * The CLEANUP clause is not only place before the CATCH clause in
212 * the source code, it also occures before in the control flow. So,
213 * resources being cleaned up cannot be used in the CATCH block. In the
214 * example, c3 gets freed before the printf placed in CATCH.
215 * -# \b variable \b uninitialization \n
216 * If resources are passed out of the scope of the
217 * TRY/CLEANUP/CATCH construct, they naturally shouldn't get
218 * cleaned up. The example above does free(3) cp1 in CLEANUP although
219 * its value was affected to globalcontext->first, invalidating this
222 * The following is fixed version of the code (annotated with the pitfall items
226 * \until end_of_good_example
231 /** @brief different kind of errors */
233 unknown_error=0, /**< unknown error */
234 arg_error, /**< Invalid argument */
235 bound_error, /**< Out of bounds argument */
236 mismatch_error, /**< The provided ID does not match */
237 not_found_error, /**< The searched element was not found */
239 system_error, /**< a syscall did fail */
240 network_error, /**< error while sending/receiving data */
241 timeout_error, /**< not quick enough, dude */
242 thread_error, /**< error while [un]locking */
243 host_error /**< host failed */
246 XBT_PUBLIC(const char *) xbt_ex_catname(xbt_errcat_t cat);
248 /** @brief Structure describing an exception */
250 char *msg; /**< human readable message */
251 xbt_errcat_t category; /**< category like HTTP (what went wrong) */
252 int value; /**< like errno (why did it went wrong) */
254 short int remote; /**< whether it was raised remotely */
255 char *host; /**< NULL locally thrown exceptions; full hostname if remote ones */
256 /* FIXME: host should be hostname:port[#thread] */
257 char *procname; /**< Name of the process who thrown this */
258 int pid; /**< PID of the process who thrown this */
259 char *file; /**< Thrown point */
260 int line; /**< Thrown point */
261 char *func; /**< Thrown point */
264 char **bt_strings; /* only filed on display (or before the network propagation) */
265 void *bt[XBT_BACKTRACE_SIZE];
268 /* declare the context type (private) */
270 __ex_mctx_t *ctx_mctx; /* permanent machine context of enclosing try/catch */
271 volatile int ctx_caught; /* temporary flag whether exception was caught */
272 volatile xbt_ex_t ctx_ex; /* temporary exception storage */
275 /* the static and dynamic initializers for a context structure */
276 #define XBT_CTX_INITIALIZER \
277 { NULL, 0, { /* content */ NULL, unknown_error, 0, \
278 /* throw point*/ 0,NULL, NULL,0, NULL, 0, NULL,\
279 /* backtrace */ 0,NULL,{NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL} } }
280 #define XBT_CTX_INITIALIZE(ctx) \
282 (ctx)->ctx_mctx = NULL; \
283 (ctx)->ctx_caught = 0; \
284 (ctx)->ctx_ex.msg = NULL; \
285 (ctx)->ctx_ex.category = 0; \
286 (ctx)->ctx_ex.value = 0; \
287 (ctx)->ctx_ex.remote = 0; \
288 (ctx)->ctx_ex.host = NULL; \
289 (ctx)->ctx_ex.procname = NULL; \
290 (ctx)->ctx_ex.pid = 0; \
291 (ctx)->ctx_ex.file = NULL; \
292 (ctx)->ctx_ex.line = 0; \
293 (ctx)->ctx_ex.func = NULL; \
294 (ctx)->ctx_ex.bt[0] = NULL; \
295 (ctx)->ctx_ex.bt[1] = NULL; \
296 (ctx)->ctx_ex.bt[2] = NULL; \
297 (ctx)->ctx_ex.bt[3] = NULL; \
298 (ctx)->ctx_ex.bt[4] = NULL; \
299 (ctx)->ctx_ex.bt[5] = NULL; \
300 (ctx)->ctx_ex.bt[6] = NULL; \
301 (ctx)->ctx_ex.bt[7] = NULL; \
302 (ctx)->ctx_ex.bt[8] = NULL; \
303 (ctx)->ctx_ex.bt[9] = NULL; \
304 (ctx)->ctx_ex.used = 0; \
305 (ctx)->ctx_ex.bt_strings = NULL; \
308 /* the exception context */
309 typedef ex_ctx_t *(*ex_ctx_cb_t)(void);
310 extern XBT_PUBLIC_DATA(ex_ctx_cb_t) __xbt_ex_ctx;
311 extern ex_ctx_t *__xbt_ex_ctx_default(void);
313 /* the termination handler */
314 typedef void (*ex_term_cb_t)(xbt_ex_t *);
315 extern XBT_PUBLIC_DATA(ex_term_cb_t) __xbt_ex_terminate;
316 extern void __xbt_ex_terminate_default(xbt_ex_t *e);
318 /** @brief Introduce a block where exception may be dealed with
323 ex_ctx_t *__xbt_ex_ctx_ptr = __xbt_ex_ctx(); \
324 int __ex_cleanup = 0; \
325 __ex_mctx_t *__ex_mctx_en; \
326 __ex_mctx_t __ex_mctx_me; \
327 __ex_mctx_en = __xbt_ex_ctx_ptr->ctx_mctx; \
328 __xbt_ex_ctx_ptr->ctx_mctx = &__ex_mctx_me; \
329 if (__ex_mctx_save(&__ex_mctx_me)) { \
332 /** @brief optional(!) block for cleanup
338 __xbt_ex_ctx_ptr->ctx_caught = 0; \
340 __ex_mctx_restored(&__ex_mctx_me); \
341 __xbt_ex_ctx_ptr->ctx_caught = 1; \
343 __xbt_ex_ctx_ptr->ctx_mctx = __ex_mctx_en; \
350 # define XBT_EX_T_CPLUSPLUSCAST (xbt_ex_t&)
352 # define XBT_EX_T_CPLUSPLUSCAST
356 /** @brief the block for catching (ie, deal with) an exception
362 if (!(__ex_cleanup)) \
363 __xbt_ex_ctx_ptr->ctx_caught = 0; \
365 if (!(__ex_cleanup)) { \
366 __ex_mctx_restored(&__ex_mctx_me); \
367 __xbt_ex_ctx_ptr->ctx_caught = 1; \
370 __xbt_ex_ctx_ptr->ctx_mctx = __ex_mctx_en; \
372 if ( !(__xbt_ex_ctx()->ctx_caught) \
373 || ((e) = XBT_EX_T_CPLUSPLUSCAST __xbt_ex_ctx()->ctx_ex, MAYDAY_CATCH(e) 0)) { \
377 #define DO_THROW(e) \
378 /* deal with the exception */ \
379 if (__xbt_ex_ctx()->ctx_mctx == NULL) \
380 __xbt_ex_terminate((xbt_ex_t *)&(e)); /* not catched */\
382 __ex_mctx_restore(__xbt_ex_ctx()->ctx_mctx); /* catched somewhere */ \
383 abort()/* nope, stupid GCC, we won't survive a THROW (this won't be reached) */
385 /** @brief Helper macro for THROWS0-6
388 * @param c: category code (integer)
389 * @param v: value (integer)
390 * @param m: message text
392 * If called from within a TRY/CATCH construct, this exception
393 * is copied into the CATCH relevant variable program control flow
394 * is derouted to the CATCH (after the optional sg_cleanup).
396 * If no TRY/CATCH construct embeeds this call, the program calls
399 * The THROW can be performed everywhere, including inside TRY,
400 * CLEANUP and CATCH blocks.
403 #define _THROW(c,v,m) \
404 do { /* change this sequence into one block */ \
405 /* build the exception */ \
406 __xbt_ex_ctx()->ctx_ex.msg = (m); \
407 __xbt_ex_ctx()->ctx_ex.category = (xbt_errcat_t)(c); \
408 __xbt_ex_ctx()->ctx_ex.value = (v); \
409 __xbt_ex_ctx()->ctx_ex.remote = 0; \
410 __xbt_ex_ctx()->ctx_ex.host = (char*)NULL; \
411 __xbt_ex_ctx()->ctx_ex.procname = (char*)xbt_procname(); \
412 __xbt_ex_ctx()->ctx_ex.pid = (*xbt_getpid)(); \
413 __xbt_ex_ctx()->ctx_ex.file = (char*)__FILE__; \
414 __xbt_ex_ctx()->ctx_ex.line = __LINE__; \
415 __xbt_ex_ctx()->ctx_ex.func = (char*)_XBT_FUNCTION; \
416 __xbt_ex_ctx()->ctx_ex.used = backtrace((void**)__xbt_ex_ctx()->ctx_ex.bt,XBT_BACKTRACE_SIZE);\
417 __xbt_ex_ctx()->ctx_ex.bt_strings = NULL; \
418 DO_THROW(__xbt_ex_ctx()->ctx_ex);\
421 /** @brief Builds and throws an exception with a string taking no arguments
423 #define THROW0(c,v,m) _THROW(c,v,(m?bprintf(m):NULL))
424 /** @brief Builds and throws an exception with a string taking one argument
426 #define THROW1(c,v,m,a1) _THROW(c,v,bprintf(m,a1))
427 /** @brief Builds and throws an exception with a string taking two arguments
429 #define THROW2(c,v,m,a1,a2) _THROW(c,v,bprintf(m,a1,a2))
430 /** @brief Builds and throws an exception with a string taking three arguments
432 #define THROW3(c,v,m,a1,a2,a3) _THROW(c,v,bprintf(m,a1,a2,a3))
433 /** @brief Builds and throws an exception with a string taking four arguments
435 #define THROW4(c,v,m,a1,a2,a3,a4) _THROW(c,v,bprintf(m,a1,a2,a3,a4))
436 /** @brief Builds and throws an exception with a string taking five arguments
438 #define THROW5(c,v,m,a1,a2,a3,a4,a5) _THROW(c,v,bprintf(m,a1,a2,a3,a4,a5))
439 /** @brief Builds and throws an exception with a string taking six arguments
441 #define THROW6(c,v,m,a1,a2,a3,a4,a5,a6) _THROW(c,v,bprintf(m,a1,a2,a3,a4,a5,a6))
442 /** @brief Builds and throws an exception with a string taking seven arguments
444 #define THROW7(c,v,m,a1,a2,a3,a4,a5,a6,a7) _THROW(c,v,bprintf(m,a1,a2,a3,a4,a5,a6,a7))
446 #define THROW_IMPOSSIBLE THROW0(unknown_error,0,"The Impossible Did Happen (yet again)")
447 #define THROW_UNIMPLEMENTED THROW1(unknown_error,0,"Function %s unimplemented",_XBT_FUNCTION)
450 # define DIE_IMPOSSIBLE xbt_assert0(0,"The Impossible Did Happen (yet again)")
452 # define DIE_IMPOSSIBLE exit(1);
455 /** @brief re-throwing of an already caught exception (ie, pass it to the upper catch block)
460 if (__xbt_ex_ctx()->ctx_mctx == NULL) \
461 __xbt_ex_terminate((xbt_ex_t *)&(__xbt_ex_ctx()->ctx_ex)); \
463 __ex_mctx_restore(__xbt_ex_ctx()->ctx_mctx); \
469 #define _XBT_PRE_RETHROW \
471 char *_xbt_ex_internal_msg = __xbt_ex_ctx()->ctx_ex.msg; \
472 __xbt_ex_ctx()->ctx_ex.msg = bprintf(
473 #define _XBT_POST_RETHROW \
474 _xbt_ex_internal_msg); \
475 free(_xbt_ex_internal_msg); \
480 /** @brief like THROW0, but adding some details to the message of an existing exception
483 #define RETHROW0(msg) _XBT_PRE_RETHROW msg, _XBT_POST_RETHROW
484 /** @brief like THROW1, but adding some details to the message of an existing exception
487 #define RETHROW1(msg,a) _XBT_PRE_RETHROW msg,a, _XBT_POST_RETHROW
488 /** @brief like THROW2, but adding some details to the message of an existing exception
491 #define RETHROW2(msg,a,b) _XBT_PRE_RETHROW msg,a,b, _XBT_POST_RETHROW
492 /** @brief like THROW3, but adding some details to the message of an existing exception
495 #define RETHROW3(msg,a,b,c) _XBT_PRE_RETHROW msg,a,b,c, _XBT_POST_RETHROW
496 /** @brief like THROW4, but adding some details to the message of an existing exception
499 #define RETHROW4(msg,a,b,c,d) _XBT_PRE_RETHROW msg,a,b,c,d, _XBT_POST_RETHROW
500 /** @brief like THROW5, but adding some details to the message of an existing exception
503 #define RETHROW5(msg,a,b,c,d,e) _XBT_PRE_RETHROW msg,a,b,c,d,e, _XBT_POST_RETHROW
505 /** @brief Exception destructor */
506 XBT_PUBLIC(void) xbt_ex_free(xbt_ex_t e);
508 /** @brief Shows a backtrace of the current location */
509 XBT_PUBLIC(void) xbt_backtrace_display_current(void);
511 /** @brief Captures a backtrace for further use */
512 XBT_PUBLIC(void) xbt_backtrace_current(xbt_ex_t *e);
513 /** @brief Display a previously captured backtrace */
514 XBT_PUBLIC(void) xbt_backtrace_display(xbt_ex_t *e);
517 #endif /* __XBT_EX_H__ */