diff options
author | Georg Brandl <georg@python.org> | 2007-08-15 14:27:07 +0000 |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2007-08-15 14:27:07 +0000 |
commit | 739c01d47b9118d04e5722333f0e6b4d0c8bdd9e (patch) | |
tree | f82b450d291927fc1758b96d981aa0610947b529 /Doc/lib/libfpectl.tex | |
parent | 2d1649094402ef393ea2b128ba2c08c3937e6b93 (diff) | |
download | cpython-git-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.tar.gz |
Delete the LaTeX doc tree.
Diffstat (limited to 'Doc/lib/libfpectl.tex')
-rw-r--r-- | Doc/lib/libfpectl.tex | 127 |
1 files changed, 0 insertions, 127 deletions
diff --git a/Doc/lib/libfpectl.tex b/Doc/lib/libfpectl.tex deleted file mode 100644 index cca2314761..0000000000 --- a/Doc/lib/libfpectl.tex +++ /dev/null @@ -1,127 +0,0 @@ -\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.} - -\note{The \module{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.} - -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 \label{fpectl-limitations}} - -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} |