1#ifndef Py_PYFPE_H
2#define Py_PYFPE_H
3#ifdef __cplusplus
4extern "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>
132extern jmp_buf PyFPE_jbuf;
133extern int PyFPE_counter;
134extern double PyFPE_dummy(void *);
135
136#define PyFPE_START_PROTECT(err_string, leave_stmt) \
137if (!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