Chris@87: #ifndef Py_PYFPE_H Chris@87: #define Py_PYFPE_H Chris@87: #ifdef __cplusplus Chris@87: extern "C" { Chris@87: #endif Chris@87: /* Chris@87: --------------------------------------------------------------------- Chris@87: / Copyright (c) 1996. \ Chris@87: | The Regents of the University of California. | Chris@87: | All rights reserved. | Chris@87: | | Chris@87: | Permission to use, copy, modify, and distribute this software for | Chris@87: | any purpose without fee is hereby granted, provided that this en- | Chris@87: | tire notice is included in all copies of any software which is or | Chris@87: | includes a copy or modification of this software and in all | Chris@87: | copies of the supporting documentation for such software. | Chris@87: | | Chris@87: | This work was produced at the University of California, Lawrence | Chris@87: | Livermore National Laboratory under contract no. W-7405-ENG-48 | Chris@87: | between the U.S. Department of Energy and The Regents of the | Chris@87: | University of California for the operation of UC LLNL. | Chris@87: | | Chris@87: | DISCLAIMER | Chris@87: | | Chris@87: | This software was prepared as an account of work sponsored by an | Chris@87: | agency of the United States Government. Neither the United States | Chris@87: | Government nor the University of California nor any of their em- | Chris@87: | ployees, makes any warranty, express or implied, or assumes any | Chris@87: | liability or responsibility for the accuracy, completeness, or | Chris@87: | usefulness of any information, apparatus, product, or process | Chris@87: | disclosed, or represents that its use would not infringe | Chris@87: | privately-owned rights. Reference herein to any specific commer- | Chris@87: | cial products, process, or service by trade name, trademark, | Chris@87: | manufacturer, or otherwise, does not necessarily constitute or | Chris@87: | imply its endorsement, recommendation, or favoring by the United | Chris@87: | States Government or the University of California. The views and | Chris@87: | opinions of authors expressed herein do not necessarily state or | Chris@87: | reflect those of the United States Government or the University | Chris@87: | of California, and shall not be used for advertising or product | Chris@87: \ endorsement purposes. / Chris@87: --------------------------------------------------------------------- Chris@87: */ Chris@87: Chris@87: /* Chris@87: * Define macros for handling SIGFPE. Chris@87: * Lee Busby, LLNL, November, 1996 Chris@87: * busby1@llnl.gov Chris@87: * Chris@87: ********************************************* Chris@87: * Overview of the system for handling SIGFPE: Chris@87: * Chris@87: * This file (Include/pyfpe.h) defines a couple of "wrapper" macros for Chris@87: * insertion into your Python C code of choice. Their proper use is Chris@87: * discussed below. The file Python/pyfpe.c defines a pair of global Chris@87: * variables PyFPE_jbuf and PyFPE_counter which are used by the signal Chris@87: * handler for SIGFPE to decide if a particular exception was protected Chris@87: * by the macros. The signal handler itself, and code for enabling the Chris@87: * generation of SIGFPE in the first place, is in a (new) Python module Chris@87: * named fpectl. This module is standard in every respect. It can be loaded Chris@87: * either statically or dynamically as you choose, and like any other Chris@87: * Python module, has no effect until you import it. Chris@87: * Chris@87: * In the general case, there are three steps toward handling SIGFPE in any Chris@87: * Python code: Chris@87: * Chris@87: * 1) Add the *_PROTECT macros to your C code as required to protect Chris@87: * dangerous floating point sections. Chris@87: * Chris@87: * 2) Turn on the inclusion of the code by adding the ``--with-fpectl'' Chris@87: * flag at the time you run configure. If the fpectl or other modules Chris@87: * which use the *_PROTECT macros are to be dynamically loaded, be Chris@87: * sure they are compiled with WANT_SIGFPE_HANDLER defined. Chris@87: * Chris@87: * 3) When python is built and running, import fpectl, and execute Chris@87: * fpectl.turnon_sigfpe(). This sets up the signal handler and enables Chris@87: * generation of SIGFPE whenever an exception occurs. From this point Chris@87: * on, any properly trapped SIGFPE should result in the Python Chris@87: * FloatingPointError exception. Chris@87: * Chris@87: * Step 1 has been done already for the Python kernel code, and should be Chris@87: * done soon for the NumPy array package. Step 2 is usually done once at Chris@87: * python install time. Python's behavior with respect to SIGFPE is not Chris@87: * changed unless you also do step 3. Thus you can control this new Chris@87: * facility at compile time, or run time, or both. Chris@87: * Chris@87: ******************************** Chris@87: * Using the macros in your code: Chris@87: * Chris@87: * static PyObject *foobar(PyObject *self,PyObject *args) Chris@87: * { Chris@87: * .... Chris@87: * PyFPE_START_PROTECT("Error in foobar", return 0) Chris@87: * result = dangerous_op(somearg1, somearg2, ...); Chris@87: * PyFPE_END_PROTECT(result) Chris@87: * .... Chris@87: * } Chris@87: * Chris@87: * If a floating point error occurs in dangerous_op, foobar returns 0 (NULL), Chris@87: * after setting the associated value of the FloatingPointError exception to Chris@87: * "Error in foobar". ``Dangerous_op'' can be a single operation, or a block Chris@87: * of code, function calls, or any combination, so long as no alternate Chris@87: * return is possible before the PyFPE_END_PROTECT macro is reached. Chris@87: * Chris@87: * The macros can only be used in a function context where an error return Chris@87: * can be recognized as signaling a Python exception. (Generally, most Chris@87: * functions that return a PyObject * will qualify.) Chris@87: * Chris@87: * Guido's original design suggestion for PyFPE_START_PROTECT and Chris@87: * PyFPE_END_PROTECT had them open and close a local block, with a locally Chris@87: * defined jmp_buf and jmp_buf pointer. This would allow recursive nesting Chris@87: * of the macros. The Ansi C standard makes it clear that such local Chris@87: * variables need to be declared with the "volatile" type qualifier to keep Chris@87: * setjmp from corrupting their values. Some current implementations seem Chris@87: * to be more restrictive. For example, the HPUX man page for setjmp says Chris@87: * Chris@87: * Upon the return from a setjmp() call caused by a longjmp(), the Chris@87: * values of any non-static local variables belonging to the routine Chris@87: * from which setjmp() was called are undefined. Code which depends on Chris@87: * such values is not guaranteed to be portable. Chris@87: * Chris@87: * I therefore decided on a more limited form of nesting, using a counter Chris@87: * variable (PyFPE_counter) to keep track of any recursion. If an exception Chris@87: * occurs in an ``inner'' pair of macros, the return will apparently Chris@87: * come from the outermost level. Chris@87: * Chris@87: */ Chris@87: Chris@87: #ifdef WANT_SIGFPE_HANDLER Chris@87: #include Chris@87: #include Chris@87: #include Chris@87: extern jmp_buf PyFPE_jbuf; Chris@87: extern int PyFPE_counter; Chris@87: extern double PyFPE_dummy(void *); Chris@87: Chris@87: #define PyFPE_START_PROTECT(err_string, leave_stmt) \ Chris@87: if (!PyFPE_counter++ && setjmp(PyFPE_jbuf)) { \ Chris@87: PyErr_SetString(PyExc_FloatingPointError, err_string); \ Chris@87: PyFPE_counter = 0; \ Chris@87: leave_stmt; \ Chris@87: } Chris@87: Chris@87: /* Chris@87: * This (following) is a heck of a way to decrement a counter. However, Chris@87: * unless the macro argument is provided, code optimizers will sometimes move Chris@87: * this statement so that it gets executed *before* the unsafe expression Chris@87: * which we're trying to protect. That pretty well messes things up, Chris@87: * of course. Chris@87: * Chris@87: * If the expression(s) you're trying to protect don't happen to return a Chris@87: * value, you will need to manufacture a dummy result just to preserve the Chris@87: * correct ordering of statements. Note that the macro passes the address Chris@87: * of its argument (so you need to give it something which is addressable). Chris@87: * If your expression returns multiple results, pass the last such result Chris@87: * to PyFPE_END_PROTECT. Chris@87: * Chris@87: * Note that PyFPE_dummy returns a double, which is cast to int. Chris@87: * This seeming insanity is to tickle the Floating Point Unit (FPU). Chris@87: * If an exception has occurred in a preceding floating point operation, Chris@87: * some architectures (notably Intel 80x86) will not deliver the interrupt Chris@87: * until the *next* floating point operation. This is painful if you've Chris@87: * already decremented PyFPE_counter. Chris@87: */ Chris@87: #define PyFPE_END_PROTECT(v) PyFPE_counter -= (int)PyFPE_dummy(&(v)); Chris@87: Chris@87: #else Chris@87: Chris@87: #define PyFPE_START_PROTECT(err_string, leave_stmt) Chris@87: #define PyFPE_END_PROTECT(v) Chris@87: Chris@87: #endif Chris@87: Chris@87: #ifdef __cplusplus Chris@87: } Chris@87: #endif Chris@87: #endif /* !Py_PYFPE_H */