home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / py2s152.zip / Include / pyfpe.h < prev    next >
C/C++ Source or Header  |  1999-06-27  |  9KB  |  177 lines
  1. #ifndef Py_PYFPE_H
  2. #define Py_PYFPE_H
  3. #ifdef __cplusplus
  4. extern "C" {
  5. #endif
  6. /*
  7.      ---------------------------------------------------------------------  
  8.     /                       Copyright (c) 1996.                           \ 
  9.    |          The Regents of the University of California.                 |
  10.    |                        All rights reserved.                           |
  11.    |                                                                       |
  12.    |   Permission to use, copy, modify, and distribute this software for   |
  13.    |   any purpose without fee is hereby granted, provided that this en-   |
  14.    |   tire notice is included in all copies of any software which is or   |
  15.    |   includes  a  copy  or  modification  of  this software and in all   |
  16.    |   copies of the supporting documentation for such software.           |
  17.    |                                                                       |
  18.    |   This  work was produced at the University of California, Lawrence   |
  19.    |   Livermore National Laboratory under  contract  no.  W-7405-ENG-48   |
  20.    |   between  the  U.S.  Department  of  Energy and The Regents of the   |
  21.    |   University of California for the operation of UC LLNL.              |
  22.    |                                                                       |
  23.    |                              DISCLAIMER                               |
  24.    |                                                                       |
  25.    |   This  software was prepared as an account of work sponsored by an   |
  26.    |   agency of the United States Government. Neither the United States   |
  27.    |   Government  nor the University of California nor any of their em-   |
  28.    |   ployees, makes any warranty, express or implied, or  assumes  any   |
  29.    |   liability  or  responsibility  for the accuracy, completeness, or   |
  30.    |   usefulness of any information,  apparatus,  product,  or  process   |
  31.    |   disclosed,   or  represents  that  its  use  would  not  infringe   |
  32.    |   privately-owned rights. Reference herein to any specific  commer-   |
  33.    |   cial  products,  process,  or  service  by trade name, trademark,   |
  34.    |   manufacturer, or otherwise, does not  necessarily  constitute  or   |
  35.    |   imply  its endorsement, recommendation, or favoring by the United   |
  36.    |   States Government or the University of California. The views  and   |
  37.    |   opinions  of authors expressed herein do not necessarily state or   |
  38.    |   reflect those of the United States Government or  the  University   |
  39.    |   of  California,  and shall not be used for advertising or product   |
  40.     \  endorsement purposes.                                              / 
  41.      ---------------------------------------------------------------------  
  42. */
  43.  
  44. /*
  45.  *       Define macros for handling SIGFPE.
  46.  *       Lee Busby, LLNL, November, 1996
  47.  *       busby1@llnl.gov
  48.  * 
  49.  *********************************************
  50.  * Overview of the system for handling SIGFPE:
  51.  * 
  52.  * This file (Include/pyfpe.h) defines a couple of "wrapper" macros for
  53.  * insertion into your Python C code of choice. Their proper use is
  54.  * discussed below. The file Python/pyfpe.c defines a pair of global
  55.  * variables PyFPE_jbuf and PyFPE_counter which are used by the signal
  56.  * handler for SIGFPE to decide if a particular exception was protected
  57.  * by the macros. The signal handler itself, and code for enabling the
  58.  * generation of SIGFPE in the first place, is in a (new) Python module
  59.  * named fpectl. This module is standard in every respect. It can be loaded
  60.  * either statically or dynamically as you choose, and like any other
  61.  * Python module, has no effect until you import it.
  62.  * 
  63.  * In the general case, there are three steps toward handling SIGFPE in any
  64.  * Python code:
  65.  * 
  66.  * 1) Add the *_PROTECT macros to your C code as required to protect
  67.  *    dangerous floating point sections.
  68.  * 
  69.  * 2) Turn on the inclusion of the code by adding the ``--with-fpectl''
  70.  *    flag at the time you run configure.  If the fpectl or other modules
  71.  *    which use the *_PROTECT macros are to be dynamically loaded, be
  72.  *    sure they are compiled with WANT_SIGFPE_HANDLER defined.
  73.  * 
  74.  * 3) When python is built and running, import fpectl, and execute
  75.  *    fpectl.turnon_sigfpe(). This sets up the signal handler and enables
  76.  *    generation of SIGFPE whenever an exception occurs. From this point
  77.  *    on, any properly trapped SIGFPE should result in the Python
  78.  *    FloatingPointError exception.
  79.  * 
  80.  * Step 1 has been done already for the Python kernel code, and should be
  81.  * done soon for the NumPy array package.  Step 2 is usually done once at
  82.  * python install time. Python's behavior with respect to SIGFPE is not
  83.  * changed unless you also do step 3. Thus you can control this new
  84.  * facility at compile time, or run time, or both.
  85.  * 
  86.  ******************************** 
  87.  * Using the macros in your code:
  88.  * 
  89.  * static PyObject *foobar(PyObject *self,PyObject *args)
  90.  * {
  91.  *     ....
  92.  *     PyFPE_START_PROTECT("Error in foobar", return 0)
  93.  *     result = dangerous_op(somearg1, somearg2, ...);
  94.  *     PyFPE_END_PROTECT(result)
  95.  *     ....
  96.  * }
  97.  * 
  98.  * If a floating point error occurs in dangerous_op, foobar returns 0 (NULL),
  99.  * after setting the associated value of the FloatingPointError exception to
  100.  * "Error in foobar". ``Dangerous_op'' can be a single operation, or a block
  101.  * of code, function calls, or any combination, so long as no alternate
  102.  * return is possible before the PyFPE_END_PROTECT macro is reached.
  103.  * 
  104.  * The macros can only be used in a function context where an error return
  105.  * can be recognized as signaling a Python exception. (Generally, most
  106.  * functions that return a PyObject * will qualify.)
  107.  * 
  108.  * Guido's original design suggestion for PyFPE_START_PROTECT and
  109.  * PyFPE_END_PROTECT had them open and close a local block, with a locally
  110.  * defined jmp_buf and jmp_buf pointer. This would allow recursive nesting
  111.  * of the macros. The Ansi C standard makes it clear that such local
  112.  * variables need to be declared with the "volatile" type qualifier to keep
  113.  * setjmp from corrupting their values. Some current implementations seem
  114.  * to be more restrictive. For example, the HPUX man page for setjmp says
  115.  * 
  116.  *   Upon the return from a setjmp() call caused by a longjmp(), the
  117.  *   values of any non-static local variables belonging to the routine
  118.  *   from which setjmp() was called are undefined. Code which depends on
  119.  *   such values is not guaranteed to be portable.
  120.  * 
  121.  * I therefore decided on a more limited form of nesting, using a counter
  122.  * variable (PyFPE_counter) to keep track of any recursion.  If an exception
  123.  * occurs in an ``inner'' pair of macros, the return will apparently
  124.  * come from the outermost level.
  125.  * 
  126.  */
  127.  
  128. #ifdef WANT_SIGFPE_HANDLER
  129. #include <signal.h>
  130. #include <setjmp.h>
  131. #include <math.h>
  132. extern jmp_buf PyFPE_jbuf;
  133. extern int PyFPE_counter;
  134. extern double PyFPE_dummy(void *);
  135.  
  136. #define PyFPE_START_PROTECT(err_string, leave_stmt) \
  137. if (!PyFPE_counter++ && setjmp(PyFPE_jbuf)) { \
  138.     PyErr_SetString(PyExc_FloatingPointError, err_string); \
  139.     PyFPE_counter = 0; \
  140.     leave_stmt; \
  141. }
  142.  
  143. /*
  144.  * This (following) is a heck of a way to decrement a counter. However,
  145.  * unless the macro argument is provided, code optimizers will sometimes move
  146.  * this statement so that it gets executed *before* the unsafe expression
  147.  * which we're trying to protect.  That pretty well messes things up,
  148.  * of course.
  149.  * 
  150.  * If the expression(s) you're trying to protect don't happen to return a
  151.  * value, you will need to manufacture a dummy result just to preserve the
  152.  * correct ordering of statements.  Note that the macro passes the address
  153.  * of its argument (so you need to give it something which is addressable).
  154.  * If your expression returns multiple results, pass the last such result
  155.  * to PyFPE_END_PROTECT.
  156.  * 
  157.  * Note that PyFPE_dummy returns a double, which is cast to int.
  158.  * This seeming insanity is to tickle the Floating Point Unit (FPU).
  159.  * If an exception has occurred in a preceding floating point operation,
  160.  * some architectures (notably Intel 80x86) will not deliver the interrupt
  161.  * until the *next* floating point operation.  This is painful if you've
  162.  * already decremented PyFPE_counter.
  163.  */
  164. #define PyFPE_END_PROTECT(v) PyFPE_counter -= (int)PyFPE_dummy(&(v));
  165.  
  166. #else
  167.  
  168. #define PyFPE_START_PROTECT(err_string, leave_stmt)
  169. #define PyFPE_END_PROTECT(v)
  170.  
  171. #endif
  172.  
  173. #ifdef __cplusplus
  174. }
  175. #endif
  176. #endif /* !Py_PYFPE_H */
  177.