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 */