| /* try.h -- try / catch / throw exception handling for C99 |
| Copyright (C) 2013, 2015, 2016, 2021 Mark Adler |
| Version 1.5 10 April 2021 |
| |
| This software is provided 'as-is', without any express or implied |
| warranty. In no event will the author be held liable for any damages |
| arising from the use of this software. |
| |
| Permission is granted to anyone to use this software for any purpose, |
| including commercial applications, and to alter it and redistribute it |
| freely, subject to the following restrictions: |
| |
| 1. The origin of this software must not be misrepresented; you must not |
| claim that you wrote the original software. If you use this software |
| in a product, an acknowledgment in the product documentation would be |
| appreciated but is not required. |
| 2. Altered source versions must be plainly marked as such, and must not be |
| misrepresented as being the original software. |
| 3. This notice may not be removed or altered from any source distribution. |
| |
| Mark Adler madler@alumni.caltech.edu |
| */ |
| |
| /* |
| Version History |
| 1.0 7 Jan 2013 - First version |
| 1.1 2 Nov 2013 - Use variadic macros and functions instead of partial |
| structure assignment, allowing arbitrary arguments |
| to printf() |
| 1.2 19 Jan 2015 - Obey setjmp() invocation limits from C standard |
| 1.3 1 Mar 2015 - Add preserve to avoid use of volatile, remove retry |
| 1.4 2 Jan 2016 - Add no-return attribute to throw() |
| 1.5 10 Apr 2021 - Portability improvements |
| */ |
| |
| /* To use, include try.h in all source files that use these operations, and |
| compile and link try.c. By default, pthread threads are used to make the |
| exception handling thread-safe. If a different threads library is required, |
| then try.h and try.c must be modified to use that environment's thread-local |
| storage for the try_stack_ pointer. try.h and try.c assume that the |
| compiler and library conform to the C99 standard, at least with respect to |
| the use of variadic macro and function arguments. */ |
| |
| /* |
| try.h provides a try / catch / throw exception handler, which allows |
| catching exceptions across any number of levels of function calls. try |
| blocks can be nested as desired, with a throw going to the end of the |
| innermost enclosing try, passing the thrown information to the associated |
| catch block. A global try stack is used, to avoid having to pass exception |
| handler information through all of the functions down to the invocations of |
| throw. The try stack is thread-unique if pthread is made available. In |
| addition to the macros try, catch, and throw, the macros preserve, always, |
| punt, and drop, and the type ball_t are created. All other symbols are of |
| the form try_*_ or TRY_*_, where the final underscore should avoid conflicts |
| with application symbols. The eight exposed names can be changed easily in |
| #defines below. |
| |
| A try block encloses code that may throw an exception with the throw() |
| macro, either directly in the try block or in any function called directly |
| or indirectly from the try block. throw() must have at least one argument, |
| which is an integer. The try block is followed by a catch block whose code |
| will be executed when throw() is called with a non-zero first argument. If |
| the first argument of throw() is zero, then execution continues after the |
| catch block. If the try block completes normally, with no throw() being |
| called, then execution continues normally after the catch block. |
| |
| There can be only one catch block. catch has one argument which must be a |
| ball_t type variable declared in the current function or block containing |
| the try and catch. That variable is loaded with the information sent by the |
| throw() for use in the catch block. |
| |
| throw() may optionally include more information that is passed to the catch |
| block in the ball_t structure. throw() can have one or more arguments, |
| where the first (possibly only) argument is an integer code. The second |
| argument can be a pointer, which will be replaced by NULL in the ball_t |
| structure if not provided. The implementation of throw() in try.c assumes |
| that if the second argument is present and is not NULL, that it is a string. |
| If that string has any percent (%) signs in it, then throw() will run that |
| string through vsnprintf() with any other arguments provided after the |
| string in the throw() invocation, and save the resulting formatted string in |
| the ball_t structure. Information on whether or not the string was |
| allocated is also maintained in the ball_t structure. |
| |
| throw() in try.c can be modified to not assume that the second argument is a |
| string. For example, an application may want to assume instead that the |
| second argument is a pointer to a set of information for use in the catch |
| block. |
| |
| The catch block may conditionally do a punt(), where the argument of punt() |
| is the argument of catch. This passes the exception on to the next |
| enclosing try/catch handler. |
| |
| If a catch block does not always complete with a punt(), it should contain a |
| drop(), where the argument of drop() is the argument of catch. This frees |
| the allocated string made if vsnprintf() was used by throw() to generate the |
| string. If printf() format strings are never used, then drop() is not |
| required. |
| |
| An always block may be placed between the try and catch block. The |
| statements in that block will be executed regardless of whether or not the |
| try block completed normally. As indicated by the ordering, the always |
| block will be executed before the catch block. This block is not named |
| "finally", since it is different from the finally block in other languages |
| which is executed after the catch block. |
| |
| A naked break or continue in a try or always block will go directly to the |
| end of that block. |
| |
| try is thread-safe when compiled with pthread.h. A throw() in a thread can |
| only be caught in the same thread. If a throw() is attempted from a thread |
| without an enclosing try in that thread, even if in another thread there is |
| a try around the pthread_create() that spawned this thread, then the throw |
| will fail on an assert. Each thread has its own thread-unique try stack, |
| which starts off empty. |
| |
| If an intermediate function does not have a need for operations in a catch |
| block other than punt, and does not need an always block, then that function |
| does not need a try block. "try { block } catch (err) { punt(err); }" is |
| the same as just "block". More precisely, it's equivalent to "do { block } |
| while (0);", which replicates the behavior of a naked break or continue in a |
| block when it follows try. throw() can be used from a function that has no |
| try. All that is necessary is that there is a try somewhere up the function |
| chain that called the current function in the current thread. |
| |
| There must not be a return in any try block, nor a goto in any try block |
| that leaves that block. The always block does not catch a return from the |
| try block. There is no check or protection for an improper use of return or |
| goto. It is up to the user to assure that this doesn't happen. If it does |
| happen, then the reference to the current try block is left on the try |
| stack, and the next throw which is supposed to go to an enclosing try would |
| instead go to this try, possibly after the enclosing function has returned. |
| Mayhem will then ensue. This may be caught by the longjmp() implementation, |
| which would report "longjmp botch" and then abort. |
| |
| Any local automatic storage variables that are modified in the try block and |
| used in the catch or always block must be declared volatile. Otherwise |
| their value in the catch or always block is indeterminate. Alternatively, a |
| preserve block can be inserted after an automatic storage variable is |
| changed in a try block. The preserve block saves the state of those |
| variables at the moment preserve is executed, and effectively continues the |
| try block. The same admonition then applies to variables modified in the |
| preserve block. The only assurance is that the catch and always block will |
| have the values of the local automatic storage variables as they were at the |
| time of the last try or preserve statement, but only if they have not been |
| modified since the last try or preserve statement. As many preserve blocks |
| as desired are permitted. |
| |
| Any statements between try and always, between try and catch if there is no |
| always, or between always and catch are part of those respective try or |
| always blocks. Use of { } to enclose those blocks is optional, but { } |
| should be used anyway for clarity, style, and to inform smart source editors |
| that the enclosed code is to be indented. Enclosing the catch block with { |
| } is not optional if there is more than one statement in the block. |
| However, even if there is just one statement in the catch block, it should |
| be enclosed in { } anyway for style and editing convenience. |
| |
| The contents of the ball_t structure after the first element (int code) can |
| be customized for the application. If ball_t is customized, then the code |
| in try.c should be updated accordingly. If there is no memory allocation in |
| throw(), then drop() can be eliminated. |
| |
| |
| Summary: |
| |
| Here is the permitted structure, where [] means an optional element |
| permitted once, and []* means an optional element permitted more than once: |
| |
| try { body } [preserve { body }]* [always { clean }] catch (ball) { action } |
| |
| body must not contain a goto or return that exits body. ball must be a |
| variable of the type ball_t. "action" must always execute either a |
| drop(ball) or a punt(ball). |
| |
| A throw() may be executed in body or at any level of functions called by |
| body, and will be processed by the innermost enclosing try in the same |
| thread: |
| |
| throw(code); |
| |
| or, |
| |
| throw(code, "string"); |
| |
| or, |
| |
| throw(code, "format string", ...); |
| |
| A throw() whose first argument is not zero, and that is caught by this try, |
| will execute "clean" followed by "action". Either a throw() whose first |
| argument is zero and caught by this try, or the normal completion of body, |
| results in the execution of just "clean", with execution continuing after |
| the catch block. If "action" does not execute a punt(ball), then execution |
| continues after the catch block. If "action" does execute a punt(ball), |
| then what was caught is thrown to the next enclosing try. |
| |
| A '} preserve {' must be inserted in body after any local automatic storage |
| variable is changed in body that can be used in the always or catch block. |
| Alternatively, such variables may be declared volatile. However the use of |
| volatile can limit optimization, and has a tendency to propagate compiler |
| warnings. |
| |
| |
| Example usage: |
| |
| ball_t err; |
| char *temp = NULL; |
| try { |
| ... do something ... |
| if (ret == -1) |
| throw(1, "bad thing happened to %s\n", me); |
| temp = malloc(sizeof(me) + 1); |
| } |
| preserve { |
| if (temp == NULL) |
| throw(2, "out of memory"); |
| ... do more ... |
| if (ret == -1) |
| throw(3, "worse thing happened to %s\n", temp); |
| ... some more code ... |
| } |
| always { |
| free(temp); |
| } |
| catch (err) { |
| fputs(err.why, stderr); |
| drop(err); |
| return err.code; |
| } |
| ... end up here if nothing bad happened ... |
| |
| |
| More involved example: |
| |
| void check_part(void) |
| { |
| ball_t err; |
| |
| try { |
| ... |
| if (part == bad1) |
| throw(1); |
| ... |
| if (part == bad2) |
| throw(1); |
| ... |
| } |
| catch (err) { |
| drop(err); |
| throw(3, "part was bad"); |
| } |
| } |
| |
| void check_input(void) |
| { |
| ... |
| if (input == wrong) |
| throw(4, "input was wrong"); |
| ... |
| if (input == stupid) |
| throw(5, "input was stupid"); |
| ... |
| check_part(); |
| ... |
| } |
| |
| void *build_something(void) |
| { |
| ball_t err; |
| volatile void *thing; |
| try { |
| thing = malloc(sizeof(struct thing)); |
| ... build up thing ... |
| check_input(); |
| ... finish building it ... |
| } |
| catch (err) { |
| free(thing); |
| punt(err); |
| } |
| return thing; |
| } |
| |
| int grand_central(void) |
| { |
| ball_t err; |
| void *thing; |
| try { |
| thing = build_something(); |
| } |
| catch (err) { |
| fputs(err.why, stderr); |
| drop(err); |
| return err.code; |
| } |
| ... use thing ... |
| free(thing); |
| return 0; |
| } |
| |
| */ |
| |
| #ifndef _TRY_H |
| #define _TRY_H |
| |
| #include <stdlib.h> |
| #include <string.h> |
| #include <assert.h> |
| #include <setjmp.h> |
| |
| /* If a POSIX pthread library is not available, then compile with NOTHREAD |
| defined. */ |
| #ifndef NOTHREAD |
| # include <pthread.h> |
| #endif |
| |
| /* The exposed names can be changed here. */ |
| #define ball_t try_ball_t_ |
| #define try TRY_TRY_ |
| #define preserve TRY_PRESERVE_ |
| #define always TRY_ALWAYS_ |
| #define catch TRY_CATCH_ |
| #define throw TRY_THROW_ |
| #define punt TRY_PUNT_ |
| #define drop TRY_DROP_ |
| |
| /* Package of an integer code and any other data to be thrown and caught. Here, |
| why is a string with information to be displayed to indicate why an |
| exception was thrown. free is true if why was allocated and should be freed |
| when no longer needed. This structure can be customized as needed, but it |
| must start with an int code. If it is customized, the try_throw_() function |
| in try.c must also be updated accordingly. As an example, why could be a |
| structure with information for use in the catch block. */ |
| typedef struct { |
| int ret; /* longjmp() return value */ |
| int code; /* integer code (required) */ |
| int free; /* if true, the message string was allocated */ |
| char *why; /* informational string or NULL */ |
| } try_ball_t_; |
| |
| /* Element in the global try stack (a linked list). */ |
| typedef struct try_s_ try_t_; |
| struct try_s_ { |
| jmp_buf env; /* state information for longjmp() to jump back */ |
| try_ball_t_ ball; /* data passed from the throw() */ |
| try_t_ *next; /* link to the next enclosing try_t, or NULL */ |
| }; |
| |
| /* Global try stack. try.c must be compiled and linked to provide the stack |
| pointer. Use thread-local storage if pthread.h is included before this. |
| Note that a throw can only be caught within the same thread. A new and |
| unique try stack is created for each thread, so any attempt to throw across |
| threads will fail with an assert, by virtue of reaching the end of the |
| stack. */ |
| #ifdef PTHREAD_ONCE_INIT |
| extern pthread_key_t try_key_; |
| void try_setup_(void); |
| # define try_stack_ ((try_t_ *)pthread_getspecific(try_key_)) |
| # define try_stack_set_(next) \ |
| do { \ |
| assert(pthread_setspecific(try_key_, next) == 0 && \ |
| "try: pthread_setspecific() failed"); \ |
| } while (0) |
| #else /* !PTHREAD_ONCE_INIT */ |
| extern try_t_ *try_stack_; |
| # define try_setup_() |
| # define try_stack_set_(next) try_stack_ = (next) |
| #endif /* PTHREAD_ONCE_INIT */ |
| |
| /* Try a block. The block should follow the invocation of try enclosed in { }. |
| The block must be immediately followed by a preserve, always, or catch. You |
| must not goto or return out of the try block. A naked break or continue in |
| the try block will go to the end of the block. */ |
| #define TRY_TRY_ \ |
| do { \ |
| try_t_ try_this_; \ |
| volatile int try_pushed_ = 1; \ |
| try_this_.ball.ret = 0; \ |
| try_this_.ball.code = 0; \ |
| try_this_.ball.free = 0; \ |
| try_this_.ball.why = NULL; \ |
| try_setup_(); \ |
| try_this_.next = try_stack_; \ |
| try_stack_set_(&try_this_); \ |
| if (setjmp(try_this_.env) == 0) \ |
| do { \ |
| |
| /* Preserve local automatic variables that were changed in the try block by |
| reissuing the setjmp(), replacing the state for the next longjmp(). The |
| preserve block should be enclosed in { }. The block must be immediately |
| followed by a preserve, always, or catch. You must not goto or return out |
| of the preserve block. A naked break or continue in the preserve block will |
| go to the end of the block. This can only follow a try or another preserve. |
| preserve effectively saves the state of local automatic variables at threat, |
| i.e. the register state, at that point so that a subsequent throw() will |
| restore those variables to that state for the always and catch blocks. |
| Changes to those variables after the preserve statement may or may not be |
| reflected in the always and catch blocks. */ |
| #define TRY_PRESERVE_ \ |
| } while (0); \ |
| if (try_this_.ball.ret == 0) if (setjmp(try_this_.env) == 0) \ |
| do { \ |
| |
| /* Execute the code between always and catch, whether or not something was |
| thrown. An always block is optional. If present, the always block must |
| follow a try or preserve block and be followed by a catch block. The always |
| block should be enclosed in { }. A naked break or continue in the always |
| block will go to the end of the block. It is permitted to use throw in the |
| always block, which will fall up to the next enclosing try. However this |
| will result in a memory leak if the original throw() allocated space for the |
| informational string. So it's best to not throw() in an always block. Keep |
| the always block simple. |
| |
| Great care must be taken if the always block uses an automatic storage |
| variable local to the enclosing function that can be modified in the try |
| block. Such variables must be declared volatile. If such a variable is not |
| declared volatile, and if the compiler elects to keep that variable in a |
| register, then the throw will restore that variable to its state at the |
| beginning of the try block, wiping out any change that occurred in the try |
| block. This can cause very confusing bugs until you remember that you |
| didn't follow this rule. */ |
| #define TRY_ALWAYS_ \ |
| } while (0); \ |
| if (try_pushed_) { \ |
| try_stack_set_(try_this_.next); \ |
| try_pushed_ = 0; \ |
| } \ |
| if (1) \ |
| do { |
| |
| /* Catch an error thrown in the preceding try block. The catch block must |
| follow catch and its parameter, and must be enclosed in { }. The catch must |
| immediately follow a try, preserve, or always block. It is permitted to use |
| throw() in the catch block, which will fall up to the next enclosing try. |
| However the ball_t passed by throw() must be freed using drop() before doing |
| another throw, to avoid a potential memory leak. The parameter of catch must |
| be a ball_t declared in the function or block containing the catch. It is |
| set to the parameters of the throw() that jumped to the catch. The catch |
| block is not executed if the first parameter of the throw() was zero. |
| |
| A catch block should end with either a punt() or a drop(). |
| |
| Great care must be taken if the catch block uses an automatic storage |
| variable local to the enclosing function that can be modified in the try |
| block. Such variables must be declared volatile or preserve must be used to |
| save their state. If such a variable is not declared volatile, and if the |
| compiler elects to keep that variable in a register, then the throw will |
| restore that variable to its state at the beginning of the most recent try |
| or preserve block, wiping out any change that occurred after the start of |
| that block. This can cause very confusing bugs until you remember that you |
| didn't follow this rule. */ |
| #define TRY_CATCH_(try_ball_) \ |
| } while (0); \ |
| if (try_pushed_) { \ |
| try_stack_set_(try_this_.next); \ |
| try_pushed_ = 0; \ |
| } \ |
| try_ball_ = try_this_.ball; \ |
| } while (0); \ |
| if (try_ball_.code) |
| |
| /* Throw an error. This can be in the try block or in any function called from |
| the try block, at any level of nesting. This will fall back to the end of |
| the first enclosing try block in the same thread, invoking the associated |
| catch block with a ball_t set to the arguments of throw(). throw() will |
| abort the program with an assert() if there is no nesting try. Make sure |
| that there's a nesting try! |
| |
| try may have one or more arguments, where the first argument is an int, the |
| optional second argument is a string, and the remaining optional arguments |
| are referred to by printf() formatting commands in the string. If there are |
| formatting commands in the string, i.e. any percent (%) signs, then |
| vsnprintf() is used to generate the formatted string from the arguments |
| before jumping to the enclosing try block. This allows throw() to use |
| information on the stack in the scope of the throw() statement, which will |
| be lost after jumping back to the enclosing try block. That formatted |
| string will use allocated memory, which is why it is important to use drop() |
| in catch blocks to free that memory, or punt() to pass the string on to |
| another catch block. Eventually some catch block down the chain will have |
| to drop() it. |
| |
| If a memory allocation fails during the execution of a throw(), then the |
| string provided to the catch block is not the formatted string at all, but |
| rather the string: "try: out of memory", with the integer code from the |
| throw() unchanged. |
| |
| If the first argument of throw is zero, then the catch block is not |
| executed. A throw(0) from a function called in the try block is equivalent |
| to a break or continue in the try block. A throw(0) should not have any |
| other arguments, to avoid a potential memory leak. There is no opportunity |
| to make use of any arguments after the 0 anyway. |
| |
| try.c must be compiled and linked to provide the try_throw_() function. */ |
| void try_throw_(int code, char *fmt, ...) |
| #if defined(__GNUC__) || defined(__has_builtin) |
| __attribute__((noreturn)) |
| #endif |
| ; |
| |
| #define TRY_THROW_(...) try_throw_(__VA_ARGS__, NULL) |
| |
| /* Punt a caught error on to the next enclosing catcher. This is normally used |
| in a catch block with same argument as the catch. */ |
| #define TRY_PUNT_(try_ball_) \ |
| do { \ |
| try_setup_(); \ |
| assert(try_stack_ != NULL && "try: naked punt"); \ |
| try_stack_->ball = try_ball_; \ |
| longjmp(try_stack_->env, 1); \ |
| } while (0) |
| |
| /* Clean up at the end of the line in a catch (no more punts). */ |
| #define TRY_DROP_(try_ball_) \ |
| do { \ |
| if (try_ball_.free) { \ |
| free(try_ball_.why); \ |
| try_ball_.free = 0; \ |
| try_ball_.why = NULL; \ |
| } \ |
| } while (0) |
| |
| #endif /* _TRY_H */ |
