/Doc/library/fpectl.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 120 lines · 84 code · 36 blank · 0 comment · 0 complexity · 45ad3f3cd96b33033adfd6917f8b71f2 MD5 · raw file

  1. :mod:`fpectl` --- Floating point exception control
  2. ==================================================
  3. .. module:: fpectl
  4. :platform: Unix
  5. :synopsis: Provide control for floating point exception handling.
  6. .. moduleauthor:: Lee Busby <busby1@llnl.gov>
  7. .. sectionauthor:: Lee Busby <busby1@llnl.gov>
  8. .. note::
  9. The :mod:`fpectl` module is not built by default, and its usage is discouraged
  10. and may be dangerous except in the hands of experts. See also the section
  11. :ref:`fpectl-limitations` on limitations for more details.
  12. .. index:: single: IEEE-754
  13. Most computers carry out floating point operations in conformance with the
  14. so-called IEEE-754 standard. On any real computer, some floating point
  15. operations produce results that cannot be expressed as a normal floating point
  16. value. For example, try ::
  17. >>> import math
  18. >>> math.exp(1000)
  19. inf
  20. >>> math.exp(1000) / math.exp(1000)
  21. nan
  22. (The example above will work on many platforms. DEC Alpha may be one exception.)
  23. "Inf" is a special, non-numeric value in IEEE-754 that stands for "infinity",
  24. and "nan" means "not a number." Note that, other than the non-numeric results,
  25. nothing special happened when you asked Python to carry out those calculations.
  26. That is in fact the default behaviour prescribed in the IEEE-754 standard, and
  27. if it works for you, stop reading now.
  28. In some circumstances, it would be better to raise an exception and stop
  29. processing at the point where the faulty operation was attempted. The
  30. :mod:`fpectl` module is for use in that situation. It provides control over
  31. floating point units from several hardware manufacturers, allowing the user to
  32. turn on the generation of :const:`SIGFPE` whenever any of the IEEE-754
  33. exceptions Division by Zero, Overflow, or Invalid Operation occurs. In tandem
  34. with a pair of wrapper macros that are inserted into the C code comprising your
  35. python system, :const:`SIGFPE` is trapped and converted into the Python
  36. :exc:`FloatingPointError` exception.
  37. The :mod:`fpectl` module defines the following functions and may raise the given
  38. exception:
  39. .. function:: turnon_sigfpe()
  40. Turn on the generation of :const:`SIGFPE`, and set up an appropriate signal
  41. handler.
  42. .. function:: turnoff_sigfpe()
  43. Reset default handling of floating point exceptions.
  44. .. exception:: FloatingPointError
  45. After :func:`turnon_sigfpe` has been executed, a floating point operation that
  46. raises one of the IEEE-754 exceptions Division by Zero, Overflow, or Invalid
  47. operation will in turn raise this standard Python exception.
  48. .. _fpectl-example:
  49. Example
  50. -------
  51. The following example demonstrates how to start up and test operation of the
  52. :mod:`fpectl` module. ::
  53. >>> import fpectl
  54. >>> import fpetest
  55. >>> fpectl.turnon_sigfpe()
  56. >>> fpetest.test()
  57. overflow PASS
  58. FloatingPointError: Overflow
  59. div by 0 PASS
  60. FloatingPointError: Division by zero
  61. [ more output from test elided ]
  62. >>> import math
  63. >>> math.exp(1000)
  64. Traceback (most recent call last):
  65. File "<stdin>", line 1, in ?
  66. FloatingPointError: in math_1
  67. .. _fpectl-limitations:
  68. Limitations and other considerations
  69. ------------------------------------
  70. Setting up a given processor to trap IEEE-754 floating point errors currently
  71. requires custom code on a per-architecture basis. You may have to modify
  72. :mod:`fpectl` to control your particular hardware.
  73. Conversion of an IEEE-754 exception to a Python exception requires that the
  74. wrapper macros ``PyFPE_START_PROTECT`` and ``PyFPE_END_PROTECT`` be inserted
  75. into your code in an appropriate fashion. Python itself has been modified to
  76. support the :mod:`fpectl` module, but many other codes of interest to numerical
  77. analysts have not.
  78. The :mod:`fpectl` module is not thread-safe.
  79. .. seealso::
  80. Some files in the source distribution may be interesting in learning more about
  81. how this module operates. The include file :file:`Include/pyfpe.h` discusses the
  82. implementation of this module at some length. :file:`Modules/fpetestmodule.c`
  83. gives several examples of use. Many additional examples can be found in
  84. :file:`Objects/floatobject.c`.