mirror of
https://github.com/python/cpython.git
synced 2025-10-31 13:41:24 +00:00
122 lines
3.9 KiB
TeX
122 lines
3.9 KiB
TeX
\section{\module{fpectl} ---
|
|
Floating point exception control}
|
|
|
|
\declaremodule{extension}{fpectl}
|
|
\platform{Unix}
|
|
\moduleauthor{Lee Busby}{busby1@llnl.gov}
|
|
\sectionauthor{Lee Busby}{busby1@llnl.gov}
|
|
\modulesynopsis{Provide control for floating point exception handling.}
|
|
|
|
Most computers carry out floating point operations\index{IEEE-754}
|
|
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
|
|
|
|
\begin{verbatim}
|
|
>>> import math
|
|
>>> math.exp(1000)
|
|
inf
|
|
>>> math.exp(1000) / math.exp(1000)
|
|
nan
|
|
\end{verbatim}
|
|
|
|
(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 \module{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 \constant{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,
|
|
\constant{SIGFPE} is trapped and converted into the Python
|
|
\exception{FloatingPointError} exception.
|
|
|
|
The \module{fpectl} module defines the following functions and
|
|
may raise the given exception:
|
|
|
|
\begin{funcdesc}{turnon_sigfpe}{}
|
|
Turn on the generation of \constant{SIGFPE},
|
|
and set up an appropriate signal handler.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{turnoff_sigfpe}{}
|
|
Reset default handling of floating point exceptions.
|
|
\end{funcdesc}
|
|
|
|
\begin{excdesc}{FloatingPointError}
|
|
After \function{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.
|
|
\end{excdesc}
|
|
|
|
|
|
\subsection{Example \label{fpectl-example}}
|
|
|
|
The following example demonstrates how to start up and test operation of
|
|
the \module{fpectl} module.
|
|
|
|
\begin{verbatim}
|
|
>>> 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
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{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 \module{fpectl} to control your particular hardware.
|
|
|
|
Conversion of an IEEE-754 exception to a Python exception requires
|
|
that the wrapper macros \code{PyFPE_START_PROTECT} and
|
|
\code{PyFPE_END_PROTECT} be inserted into your code in an appropriate
|
|
fashion. Python itself has been modified to support the
|
|
\module{fpectl} module, but many other codes of interest to numerical
|
|
analysts have not.
|
|
|
|
The \module{fpectl} module is not thread-safe.
|
|
|
|
\begin{seealso}
|
|
\seetext{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}.}
|
|
\end{seealso}
|