/Doc/library/fpectl.rst
http://unladen-swallow.googlecode.com/ · ReStructuredText · 120 lines · 84 code · 36 blank · 0 comment · 0 complexity · 45ad3f3cd96b33033adfd6917f8b71f2 MD5 · raw file
- :mod:`fpectl` --- Floating point exception control
- ==================================================
- .. module:: fpectl
- :platform: Unix
- :synopsis: Provide control for floating point exception handling.
- .. moduleauthor:: Lee Busby <busby1@llnl.gov>
- .. sectionauthor:: Lee Busby <busby1@llnl.gov>
- .. note::
- The :mod:`fpectl` module is not built by default, and its usage is discouraged
- and may be dangerous except in the hands of experts. See also the section
- :ref:`fpectl-limitations` on limitations for more details.
- .. index:: single: IEEE-754
- Most computers carry out floating point operations in conformance with the
- so-called IEEE-754 standard. On any real computer, some floating point
- operations produce results that cannot be expressed as a normal floating point
- value. For example, try ::
- >>> import math
- >>> math.exp(1000)
- inf
- >>> math.exp(1000) / math.exp(1000)
- nan
- (The example above will work on many platforms. DEC Alpha may be one exception.)
- "Inf" is a special, non-numeric value in IEEE-754 that stands for "infinity",
- and "nan" means "not a number." Note that, other than the non-numeric results,
- nothing special happened when you asked Python to carry out those calculations.
- That is in fact the default behaviour prescribed in the IEEE-754 standard, and
- if it works for you, stop reading now.
- In some circumstances, it would be better to raise an exception and stop
- processing at the point where the faulty operation was attempted. The
- :mod:`fpectl` module is for use in that situation. It provides control over
- floating point units from several hardware manufacturers, allowing the user to
- turn on the generation of :const:`SIGFPE` whenever any of the IEEE-754
- exceptions Division by Zero, Overflow, or Invalid Operation occurs. In tandem
- with a pair of wrapper macros that are inserted into the C code comprising your
- python system, :const:`SIGFPE` is trapped and converted into the Python
- :exc:`FloatingPointError` exception.
- The :mod:`fpectl` module defines the following functions and may raise the given
- exception:
- .. function:: turnon_sigfpe()
- Turn on the generation of :const:`SIGFPE`, and set up an appropriate signal
- handler.
- .. function:: turnoff_sigfpe()
- Reset default handling of floating point exceptions.
- .. exception:: FloatingPointError
- After :func:`turnon_sigfpe` has been executed, a floating point operation that
- raises one of the IEEE-754 exceptions Division by Zero, Overflow, or Invalid
- operation will in turn raise this standard Python exception.
- .. _fpectl-example:
- Example
- -------
- The following example demonstrates how to start up and test operation of the
- :mod:`fpectl` module. ::
- >>> import fpectl
- >>> import fpetest
- >>> fpectl.turnon_sigfpe()
- >>> fpetest.test()
- overflow PASS
- FloatingPointError: Overflow
- div by 0 PASS
- FloatingPointError: Division by zero
- [ more output from test elided ]
- >>> import math
- >>> math.exp(1000)
- Traceback (most recent call last):
- File "<stdin>", line 1, in ?
- FloatingPointError: in math_1
- .. _fpectl-limitations:
- Limitations and other considerations
- ------------------------------------
- Setting up a given processor to trap IEEE-754 floating point errors currently
- requires custom code on a per-architecture basis. You may have to modify
- :mod:`fpectl` to control your particular hardware.
- Conversion of an IEEE-754 exception to a Python exception requires that the
- wrapper macros ``PyFPE_START_PROTECT`` and ``PyFPE_END_PROTECT`` be inserted
- into your code in an appropriate fashion. Python itself has been modified to
- support the :mod:`fpectl` module, but many other codes of interest to numerical
- analysts have not.
- The :mod:`fpectl` module is not thread-safe.
- .. seealso::
- Some files in the source distribution may be interesting in learning more about
- how this module operates. The include file :file:`Include/pyfpe.h` discusses the
- implementation of this module at some length. :file:`Modules/fpetestmodule.c`
- gives several examples of use. Many additional examples can be found in
- :file:`Objects/floatobject.c`.