4.7.3 Floating-Point Environment

The IEEE 754-2008 computation model includes a persistent rounding mode, exception flags, and exception-handling modes. In MIT/GNU Scheme, the floating-point environment is per-thread. However, because saving and restoring the floating-point environment is expensive, it is maintained only for those threads that have touched the floating-point environment explicitly, either:

• during a procedure such as flo:with-exceptions-trapped that establishes a change to the floating-point environment for a dynamic extent, or
• after flo:set-environment! to a non-default environment (but not after flo:set-environment! to the default environment), or
• after various other procedures such as flo:clear-exceptions! that explicitly change the floating-point environment.

The default environment is as in IEEE 754-2008: no exceptions are trapped, and rounding is to nearest with ties broken to even. The set of exception flags in the default environment is indeterminate — callers must enter a per-thread environment, e.g. by calling flo:clear-exceptions!, before acting on the exception flags. Like the default environment, a per-thread environment initially has no exceptions trapped and rounds to nearest with ties to even.

A floating-point environment descriptor is a machine-dependent object representing the IEEE 754-2008 floating-point rounding mode, exception flags, and exception-handling mode. Users should not inspect a floating-point environment descriptor other than to use it with the procedures here; its representation may vary from system to system.

procedure: flo:default-environment

Returns a descriptor for the default environment, with no exceptions trapped and round-to-nearest/ties-to-even.

procedure: flo:environment

procedure: flo:set-environment! floenv

procedure: flo:update-environment! floenv

Flo:environment returns a descriptor for the current floating-point environment. Flo:set-environment! replaces the current floating-point environment by floenv. Flo:update-environment! does likewise, but re-raises any exceptions that were already raised in the current floating-point environment, which may cause a trap if floenv also traps them.

Flo:update-environment! is usually used together with flo:defer-exception-traps! to defer potentially trapping on exceptions in a large intermediate computation until the end.

procedure: flo:preserving-environment thunk

Saves the current floating-point environment if any and calls thunk. On exit from thunk, including non-local exit, saves thunk’s floating-point environment and restores the original floating-point environment as if with flo:set-environment!. On re-entry into thunk, restores thunk’s floating-point environment.

Note: Flo:preserving-environment does not enter a per-thread environment. If the current thread is in the default environment, the exception flags are indeterminate, and remain so inside flo:preserving-environment. Callers interested in using the exception flags should start inside flo:preserving-environment by clearing them with flo:clear-exceptions!.