"Fossies" - the Fresh Open Source Software Archive

Member "pigz-2.8/try.h" (20 Aug 2023, 23043 Bytes) of package /linux/privat/pigz-2.8.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "try.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 2.7_vs_2.8.

    1 /* try.h -- try / catch / throw exception handling for C99
    2   Copyright (C) 2013, 2015, 2016, 2021 Mark Adler
    3   Version 1.5  10 April 2021
    5   This software is provided 'as-is', without any express or implied
    6   warranty.  In no event will the author be held liable for any damages
    7   arising from the use of this software.
    9   Permission is granted to anyone to use this software for any purpose,
   10   including commercial applications, and to alter it and redistribute it
   11   freely, subject to the following restrictions:
   13   1. The origin of this software must not be misrepresented; you must not
   14      claim that you wrote the original software. If you use this software
   15      in a product, an acknowledgment in the product documentation would be
   16      appreciated but is not required.
   17   2. Altered source versions must be plainly marked as such, and must not be
   18      misrepresented as being the original software.
   19   3. This notice may not be removed or altered from any source distribution.
   21   Mark Adler    madler@alumni.caltech.edu
   22  */
   24 /*
   25     Version History
   26     1.0    7 Jan 2013   - First version
   27     1.1    2 Nov 2013   - Use variadic macros and functions instead of partial
   28                           structure assignment, allowing arbitrary arguments
   29                           to printf()
   30     1.2   19 Jan 2015   - Obey setjmp() invocation limits from C standard
   31     1.3    1 Mar 2015   - Add preserve to avoid use of volatile, remove retry
   32     1.4    2 Jan 2016   - Add no-return attribute to throw()
   33     1.5   10 Apr 2021   - Portability improvements
   34  */
   36 /* To use, include try.h in all source files that use these operations, and
   37    compile and link try.c.  By default, pthread threads are used to make the
   38    exception handling thread-safe. If a different threads library is required,
   39    then try.h and try.c must be modified to use that environment's thread-local
   40    storage for the try_stack_ pointer.  try.h and try.c assume that the
   41    compiler and library conform to the C99 standard, at least with respect to
   42    the use of variadic macro and function arguments. */
   44 /*
   45    try.h provides a try / catch / throw exception handler, which allows
   46    catching exceptions across any number of levels of function calls.  try
   47    blocks can be nested as desired, with a throw going to the end of the
   48    innermost enclosing try, passing the thrown information to the associated
   49    catch block.  A global try stack is used, to avoid having to pass exception
   50    handler information through all of the functions down to the invocations of
   51    throw.  The try stack is thread-unique if pthread is made available.  In
   52    addition to the macros try, catch, and throw, the macros preserve, always,
   53    punt, and drop, and the type ball_t are created.  All other symbols are of
   54    the form try_*_ or TRY_*_, where the final underscore should avoid conflicts
   55    with application symbols. The eight exposed names can be changed easily in
   56    #defines below.
   58    A try block encloses code that may throw an exception with the throw()
   59    macro, either directly in the try block or in any function called directly
   60    or indirectly from the try block.  throw() must have at least one argument,
   61    which is an integer.  The try block is followed by a catch block whose code
   62    will be executed when throw() is called with a non-zero first argument.  If
   63    the first argument of throw() is zero, then execution continues after the
   64    catch block.  If the try block completes normally, with no throw() being
   65    called, then execution continues normally after the catch block.
   67    There can be only one catch block.  catch has one argument which must be a
   68    ball_t type variable declared in the current function or block containing
   69    the try and catch.  That variable is loaded with the information sent by the
   70    throw() for use in the catch block.
   72    throw() may optionally include more information that is passed to the catch
   73    block in the ball_t structure.  throw() can have one or more arguments,
   74    where the first (possibly only) argument is an integer code.  The second
   75    argument can be a pointer, which will be replaced by NULL in the ball_t
   76    structure if not provided.  The implementation of throw() in try.c assumes
   77    that if the second argument is present and is not NULL, that it is a string.
   78    If that string has any percent (%) signs in it, then throw() will run that
   79    string through vsnprintf() with any other arguments provided after the
   80    string in the throw() invocation, and save the resulting formatted string in
   81    the ball_t structure.  Information on whether or not the string was
   82    allocated is also maintained in the ball_t structure.
   84    throw() in try.c can be modified to not assume that the second argument is a
   85    string.  For example, an application may want to assume instead that the
   86    second argument is a pointer to a set of information for use in the catch
   87    block.
   89    The catch block may conditionally do a punt(), where the argument of punt()
   90    is the argument of catch.  This passes the exception on to the next
   91    enclosing try/catch handler.
   93    If a catch block does not always complete with a punt(), it should contain a
   94    drop(), where the argument of drop() is the argument of catch.  This frees
   95    the allocated string made if vsnprintf() was used by throw() to generate the
   96    string.  If printf() format strings are never used, then drop() is not
   97    required.
   99    An always block may be placed between the try and catch block.  The
  100    statements in that block will be executed regardless of whether or not the
  101    try block completed normally.  As indicated by the ordering, the always
  102    block will be executed before the catch block.  This block is not named
  103    "finally", since it is different from the finally block in other languages
  104    which is executed after the catch block.
  106    A naked break or continue in a try or always block will go directly to the
  107    end of that block.
  109    try is thread-safe when compiled with pthread.h.  A throw() in a thread can
  110    only be caught in the same thread.  If a throw() is attempted from a thread
  111    without an enclosing try in that thread, even if in another thread there is
  112    a try around the pthread_create() that spawned this thread, then the throw
  113    will fail on an assert.  Each thread has its own thread-unique try stack,
  114    which starts off empty.
  116    If an intermediate function does not have a need for operations in a catch
  117    block other than punt, and does not need an always block, then that function
  118    does not need a try block.  "try { block } catch (err) { punt(err); }" is
  119    the same as just "block".  More precisely, it's equivalent to "do { block }
  120    while (0);", which replicates the behavior of a naked break or continue in a
  121    block when it follows try.  throw() can be used from a function that has no
  122    try.  All that is necessary is that there is a try somewhere up the function
  123    chain that called the current function in the current thread.
  125    There must not be a return in any try block, nor a goto in any try block
  126    that leaves that block.  The always block does not catch a return from the
  127    try block.  There is no check or protection for an improper use of return or
  128    goto.  It is up to the user to assure that this doesn't happen.  If it does
  129    happen, then the reference to the current try block is left on the try
  130    stack, and the next throw which is supposed to go to an enclosing try would
  131    instead go to this try, possibly after the enclosing function has returned.
  132    Mayhem will then ensue.  This may be caught by the longjmp() implementation,
  133    which would report "longjmp botch" and then abort.
  135    Any local automatic storage variables that are modified in the try block and
  136    used in the catch or always block must be declared volatile.  Otherwise
  137    their value in the catch or always block is indeterminate.  Alternatively, a
  138    preserve block can be inserted after an automatic storage variable is
  139    changed in a try block.  The preserve block saves the state of those
  140    variables at the moment preserve is executed, and effectively continues the
  141    try block.  The same admonition then applies to variables modified in the
  142    preserve block.  The only assurance is that the catch and always block will
  143    have the values of the local automatic storage variables as they were at the
  144    time of the last try or preserve statement, but only if they have not been
  145    modified since the last try or preserve statement.  As many preserve blocks
  146    as desired are permitted.
  148    Any statements between try and always, between try and catch if there is no
  149    always, or between always and catch are part of those respective try or
  150    always blocks.  Use of { } to enclose those blocks is optional, but { }
  151    should be used anyway for clarity, style, and to inform smart source editors
  152    that the enclosed code is to be indented.  Enclosing the catch block with {
  153    } is not optional if there is more than one statement in the block.
  154    However, even if there is just one statement in the catch block, it should
  155    be enclosed in { } anyway for style and editing convenience.
  157    The contents of the ball_t structure after the first element (int code) can
  158    be customized for the application.  If ball_t is customized, then the code
  159    in try.c should be updated accordingly.  If there is no memory allocation in
  160    throw(), then drop() can be eliminated.
  163    Summary:
  165    Here is the permitted structure, where [] means an optional element
  166    permitted once, and []* means an optional element permitted more than once:
  168    try { body } [preserve { body }]* [always { clean }] catch (ball) { action }
  170    body must not contain a goto or return that exits body.  ball must be a
  171    variable of the type ball_t.  "action" must always execute either a
  172    drop(ball) or a punt(ball).
  174    A throw() may be executed in body or at any level of functions called by
  175    body, and will be processed by the innermost enclosing try in the same
  176    thread:
  178        throw(code);
  180    or,
  182        throw(code, "string");
  184    or,
  186        throw(code, "format string", ...);
  188    A throw() whose first argument is not zero, and that is caught by this try,
  189    will execute "clean" followed by "action".  Either a throw() whose first
  190    argument is zero and caught by this try, or the normal completion of body,
  191    results in the execution of just "clean", with execution continuing after
  192    the catch block.  If "action" does not execute a punt(ball), then execution
  193    continues after the catch block.  If "action" does execute a punt(ball),
  194    then what was caught is thrown to the next enclosing try.
  196    A '} preserve {' must be inserted in body after any local automatic storage
  197    variable is changed in body that can be used in the always or catch block.
  198    Alternatively, such variables may be declared volatile.  However the use of
  199    volatile can limit optimization, and has a tendency to propagate compiler
  200    warnings.
  203    Example usage:
  205     ball_t err;
  206     char *temp = NULL;
  207     try {
  208         ... do something ...
  209         if (ret == -1)
  210             throw(1, "bad thing happened to %s\n", me);
  211         temp = malloc(sizeof(me) + 1);
  212     }
  213     preserve {
  214         if (temp == NULL)
  215             throw(2, "out of memory");
  216         ... do more ...
  217         if (ret == -1)
  218             throw(3, "worse thing happened to %s\n", temp);
  219         ... some more code ...
  220     }
  221     always {
  222         free(temp);
  223     }
  224     catch (err) {
  225         fputs(err.why, stderr);
  226         drop(err);
  227         return err.code;
  228     }
  229     ... end up here if nothing bad happened ...
  232    More involved example:
  234     void check_part(void)
  235     {
  236         ball_t err;
  238         try {
  239             ...
  240             if (part == bad1)
  241                 throw(1);
  242             ...
  243             if (part == bad2)
  244                 throw(1);
  245             ...
  246         }
  247         catch (err) {
  248             drop(err);
  249             throw(3, "part was bad");
  250         }
  251     }
  253     void check_input(void)
  254     {
  255         ...
  256         if (input == wrong)
  257             throw(4, "input was wrong");
  258         ...
  259         if (input == stupid)
  260             throw(5, "input was stupid");
  261         ...
  262         check_part();
  263         ...
  264     }
  266     void *build_something(void)
  267     {
  268         ball_t err;
  269         volatile void *thing;
  270         try {
  271             thing = malloc(sizeof(struct thing));
  272             ... build up thing ...
  273             check_input();
  274             ... finish building it ...
  275         }
  276         catch (err) {
  277             free(thing);
  278             punt(err);
  279         }
  280         return thing;
  281     }
  283     int grand_central(void)
  284     {
  285         ball_t err;
  286         void *thing;
  287         try {
  288             thing = build_something();
  289         }
  290         catch (err) {
  291             fputs(err.why, stderr);
  292             drop(err);
  293             return err.code;
  294         }
  295         ... use thing ...
  296         free(thing);
  297         return 0;
  298     }
  300  */
  302 #ifndef _TRY_H
  303 #define _TRY_H
  305 #include <stdlib.h>
  306 #include <string.h>
  307 #include <assert.h>
  308 #include <setjmp.h>
  310 /* If a POSIX pthread library is not available, then compile with NOTHREAD
  311    defined. */
  312 #ifndef NOTHREAD
  313 #  include <pthread.h>
  314 #endif
  316 /* The exposed names can be changed here. */
  317 #define ball_t try_ball_t_
  318 #define try TRY_TRY_
  319 #define preserve TRY_PRESERVE_
  320 #define always TRY_ALWAYS_
  321 #define catch TRY_CATCH_
  322 #define throw TRY_THROW_
  323 #define punt TRY_PUNT_
  324 #define drop TRY_DROP_
  326 /* Package of an integer code and any other data to be thrown and caught. Here,
  327    why is a string with information to be displayed to indicate why an
  328    exception was thrown.  free is true if why was allocated and should be freed
  329    when no longer needed.  This structure can be customized as needed, but it
  330    must start with an int code.  If it is customized, the try_throw_() function
  331    in try.c must also be updated accordingly.  As an example, why could be a
  332    structure with information for use in the catch block. */
  333 typedef struct {
  334     int ret;            /* longjmp() return value */
  335     int code;           /* integer code (required) */
  336     int free;           /* if true, the message string was allocated */
  337     char *why;          /* informational string or NULL */
  338 } try_ball_t_;
  340 /* Element in the global try stack (a linked list). */
  341 typedef struct try_s_ try_t_;
  342 struct try_s_ {
  343     jmp_buf env;        /* state information for longjmp() to jump back */
  344     try_ball_t_ ball;   /* data passed from the throw() */
  345     try_t_ *next;       /* link to the next enclosing try_t, or NULL */
  346 };
  348 /* Global try stack.  try.c must be compiled and linked to provide the stack
  349    pointer.  Use thread-local storage if pthread.h is included before this.
  350    Note that a throw can only be caught within the same thread.  A new and
  351    unique try stack is created for each thread, so any attempt to throw across
  352    threads will fail with an assert, by virtue of reaching the end of the
  353    stack. */
  354 #ifdef PTHREAD_ONCE_INIT
  355     extern pthread_key_t try_key_;
  356     void try_setup_(void);
  357 #   define try_stack_ ((try_t_ *)pthread_getspecific(try_key_))
  358 #   define try_stack_set_(next) \
  359         do { \
  360             int ret = pthread_setspecific(try_key_, next); \
  361             assert(ret == 0 && "try: pthread_setspecific() failed"); \
  362         } while (0)
  363 #else /* !PTHREAD_ONCE_INIT */
  364     extern try_t_ *try_stack_;
  365 #   define try_setup_()
  366 #   define try_stack_set_(next) try_stack_ = (next)
  367 #endif /* PTHREAD_ONCE_INIT */
  369 /* Try a block.  The block should follow the invocation of try enclosed in { }.
  370    The block must be immediately followed by a preserve, always, or catch.  You
  371    must not goto or return out of the try block.  A naked break or continue in
  372    the try block will go to the end of the block. */
  373 #define TRY_TRY_ \
  374     do { \
  375         try_t_ try_this_; \
  376         volatile int try_pushed_ = 1; \
  377         try_this_.ball.ret = 0; \
  378         try_this_.ball.code = 0; \
  379         try_this_.ball.free = 0; \
  380         try_this_.ball.why = NULL; \
  381         try_setup_(); \
  382         try_this_.next = try_stack_; \
  383         try_stack_set_(&try_this_); \
  384         if (setjmp(try_this_.env) == 0) \
  385             do { \
  387 /* Preserve local automatic variables that were changed in the try block by
  388    reissuing the setjmp(), replacing the state for the next longjmp().  The
  389    preserve block should be enclosed in { }.  The block must be immediately
  390    followed by a preserve, always, or catch.  You must not goto or return out
  391    of the preserve block.  A naked break or continue in the preserve block will
  392    go to the end of the block.  This can only follow a try or another preserve.
  393    preserve effectively saves the state of local automatic variables at threat,
  394    i.e. the register state, at that point so that a subsequent throw() will
  395    restore those variables to that state for the always and catch blocks.
  396    Changes to those variables after the preserve statement may or may not be
  397    reflected in the always and catch blocks. */
  398 #define TRY_PRESERVE_ \
  399             } while (0); \
  400         if (try_this_.ball.ret == 0) if (setjmp(try_this_.env) == 0) \
  401             do { \
  403 /* Execute the code between always and catch, whether or not something was
  404    thrown.  An always block is optional.  If present, the always block must
  405    follow a try or preserve block and be followed by a catch block.  The always
  406    block should be enclosed in { }.  A naked break or continue in the always
  407    block will go to the end of the block.  It is permitted to use throw in the
  408    always block, which will fall up to the next enclosing try.  However this
  409    will result in a memory leak if the original throw() allocated space for the
  410    informational string.  So it's best to not throw() in an always block.  Keep
  411    the always block simple.
  413    Great care must be taken if the always block uses an automatic storage
  414    variable local to the enclosing function that can be modified in the try
  415    block.  Such variables must be declared volatile.  If such a variable is not
  416    declared volatile, and if the compiler elects to keep that variable in a
  417    register, then the throw will restore that variable to its state at the
  418    beginning of the try block, wiping out any change that occurred in the try
  419    block.  This can cause very confusing bugs until you remember that you
  420    didn't follow this rule. */
  421 #define TRY_ALWAYS_ \
  422             } while (0); \
  423         if (try_pushed_) { \
  424             try_stack_set_(try_this_.next); \
  425             try_pushed_ = 0; \
  426         } \
  427         if (1) \
  428             do {
  430 /* Catch an error thrown in the preceding try block.  The catch block must
  431    follow catch and its parameter, and must be enclosed in { }.  The catch must
  432    immediately follow a try, preserve, or always block.  It is permitted to use
  433    throw() in the catch block, which will fall up to the next enclosing try.
  434    However the ball_t passed by throw() must be freed using drop() before doing
  435    another throw, to avoid a potential memory leak. The parameter of catch must
  436    be a ball_t declared in the function or block containing the catch.  It is
  437    set to the parameters of the throw() that jumped to the catch.  The catch
  438    block is not executed if the first parameter of the throw() was zero.
  440    A catch block should end with either a punt() or a drop().
  442    Great care must be taken if the catch block uses an automatic storage
  443    variable local to the enclosing function that can be modified in the try
  444    block.  Such variables must be declared volatile or preserve must be used to
  445    save their state.  If such a variable is not declared volatile, and if the
  446    compiler elects to keep that variable in a register, then the throw will
  447    restore that variable to its state at the beginning of the most recent try
  448    or preserve block, wiping out any change that occurred after the start of
  449    that block.  This can cause very confusing bugs until you remember that you
  450    didn't follow this rule. */
  451 #define TRY_CATCH_(try_ball_) \
  452             } while (0); \
  453         if (try_pushed_) { \
  454             try_stack_set_(try_this_.next); \
  455             try_pushed_ = 0; \
  456         } \
  457         try_ball_ = try_this_.ball; \
  458     } while (0); \
  459     if (try_ball_.code)
  461 /* Throw an error.  This can be in the try block or in any function called from
  462    the try block, at any level of nesting.  This will fall back to the end of
  463    the first enclosing try block in the same thread, invoking the associated
  464    catch block with a ball_t set to the arguments of throw().  throw() will
  465    abort the program with an assert() if there is no nesting try.  Make sure
  466    that there's a nesting try!
  468    try may have one or more arguments, where the first argument is an int, the
  469    optional second argument is a string, and the remaining optional arguments
  470    are referred to by printf() formatting commands in the string.  If there are
  471    formatting commands in the string, i.e. any percent (%) signs, then
  472    vsnprintf() is used to generate the formatted string from the arguments
  473    before jumping to the enclosing try block.  This allows throw() to use
  474    information on the stack in the scope of the throw() statement, which will
  475    be lost after jumping back to the enclosing try block.  That formatted
  476    string will use allocated memory, which is why it is important to use drop()
  477    in catch blocks to free that memory, or punt() to pass the string on to
  478    another catch block.  Eventually some catch block down the chain will have
  479    to drop() it.
  481    If a memory allocation fails during the execution of a throw(), then the
  482    string provided to the catch block is not the formatted string at all, but
  483    rather the string: "try: out of memory", with the integer code from the
  484    throw() unchanged.
  486    If the first argument of throw is zero, then the catch block is not
  487    executed.  A throw(0) from a function called in the try block is equivalent
  488    to a break or continue in the try block.  A throw(0) should not have any
  489    other arguments, to avoid a potential memory leak.  There is no opportunity
  490    to make use of any arguments after the 0 anyway.
  492    try.c must be compiled and linked to provide the try_throw_() function. */
  493 void try_throw_(int code, char *fmt, ...)
  494 #if defined(__GNUC__) || defined(__has_builtin)
  495                                                 __attribute__((noreturn))
  496 #endif
  497     ;
  499 #define TRY_THROW_(...) try_throw_(__VA_ARGS__, NULL)
  501 /* Punt a caught error on to the next enclosing catcher.  This is normally used
  502    in a catch block with same argument as the catch. */
  503 #define TRY_PUNT_(try_ball_) \
  504     do { \
  505         try_setup_(); \
  506         assert(try_stack_ != NULL && "try: naked punt"); \
  507         try_stack_->ball = try_ball_; \
  508         longjmp(try_stack_->env, 1); \
  509     } while (0)
  511 /* Clean up at the end of the line in a catch (no more punts). */
  512 #define TRY_DROP_(try_ball_) \
  513     do { \
  514         if (try_ball_.free) { \
  515             free(try_ball_.why); \
  516             try_ball_.free = 0; \
  517             try_ball_.why = NULL; \
  518         } \
  519     } while (0)
  521 #endif /* _TRY_H */