6.10.2 Compensations API

The compensations mechanism is built on top of the unwind protection mechanism:

• All the ?alloc and ?body forms end in the body of a thunk; the compensations are evaluated when the dynamic extent of the call to such thunk is terminated, as defined by the unwind protection mechanism.
• All the ?release forms end in the body of a clean–up procedure; such forms are evaluated in the dynamic environment of the syntax use that allocates the compensations stack.

Syntax: with-compensations ?body0 ?body …

Allocate a new compensations stack, then evaluate all the ?body forms in the given order. If no error occurs: call run-compensations, reset the compensations stack to empty, finally return the result value of the last ?body form.

If the dynamic extent of the evaluation of the ?body forms is terminated: the accumulated compensations are evaluated in reverse order.

Syntax: with-compensations/on-error ?body0 ?body …

Allocate a new compensations stack, then evaluate all the ?body forms in the given order. If no error occurs: reset the compensations stack to empty, return the result value of the last ?body form.

If the dynamic extent of the evaluation of the ?body forms is terminated by escaping from the body directly or by escaping from the body while handling a raised a exception: the accumulated compensations are evaluated in reverse order.

Function: run-compensations

Evaluate all the compensation thunks in the current stack, in last in/first out order; compensation thunks are called in the current dynamic environment. If a compensation thunk raises an exception: the exception is blocked and silently discarded.

This function should be called only inside the dynamic environment prepared by with-compensations and similar syntaxes. It can be called multiple times: every time the compensation thunks are consumed and removed from the stack.

Syntax: with-compensation-handler ?release-thunk ?alloc-thunk

First push ?release-thunk on the current compensations stack, then evaluate ?alloc-thunk. Return the results of evaluating ?alloc-thunk.

Syntax: compensate ?alloc0 ?alloc … (with ?release0 ?release …)

Auxiliary Fluid Syntax: with

Auxiliary Fluid Syntax: <>

First evaluate all the ?alloc expressions then, only if they perform a normal return: push one thunk holding all the ?release forms on the current compensations stack. Return the result of the last ?alloc expression.

While expanding the ?release forms: the fluid syntax <> is bound to an identifier referencing the object returned by the ?alloc forms; this allows to code:

(define (make-compensated-object)
  (compensate
      (make-new-object)
    (with
      (destroy-object <>))))

rather than:

(define (make-compensated-object)
  (receive-and-return (obj)
    (compensate
        (make-new-object)
      (with
        (destroy-object obj)))))

Syntax: push-compensation ?release0 ?release …

Push a thunk holding the ?release forms on the current compensations stack.

Function: push-compensation-thunk thunk

Push the given thunk on the current compensations stack.