Floating-Point Environment (MIT/GNU Scheme 12.0.90)

Next: Floating-Point Exceptions, Previous: Flonum Operations, Up: Fixnum and Flonum Operations [Contents][Index]

#### 4.8.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:with-default-environment thunk ¶

  Calls thunk in the default floating-point environment, and restores the caller’s floating-point environment afterward. Equivalent to:

      (flo:preserving-environment
       (lambda ()
         (flo:set-environment! (flo:default-environment))
         (thunk)))

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!`.

Next: Floating-Point Exceptions, Previous: Flonum Operations, Up: Fixnum and Flonum Operations [Contents][Index]