Warning: This is the manual of the legacy Guile 2.0 series. You may want to read the manual of the current stable series instead.

9.3.6.9 Dynamic Environment Instructions

Guile’s virtual machine has low-level support for dynamic-wind, dynamic binding, and composable prompts and aborts.

Instruction: wind

Pop an unwind thunk and a wind thunk from the stack, in that order, and push them onto the “dynamic stack”. The unwind thunk will be called on nonlocal exits, and the wind thunk on reentries. Used to implement dynamic-wind.

Note that neither thunk is actually called; the compiler should emit calls to wind and unwind for the normal dynamic-wind control flow. See Dynamic Wind.

Instruction: unwind

Pop off the top entry from the “dynamic stack”, for example, a wind/unwind thunk pair. unwind instructions should be properly paired with their winding instructions, like wind.

Instruction: wind-fluids n

Pop off n values and n fluids from the stack, in that order. Set the fluids to the values by creating a with-fluids object and pushing that object on the dynamic stack. See Fluids and Dynamic States.

Instruction: unwind-fluids

Pop a with-fluids object from the dynamic stack, and swap the current values of its fluids with the saved values of its fluids. In this way, the dynamic environment is left as it was before the corresponding wind-fluids instruction was processed.

Instruction: fluid-ref

Pop a fluid from the stack, and push its current value.

Instruction: fluid-set

Pop a value and a fluid from the stack, in that order, and set the fluid to the value.

Instruction: prompt escape-only? offset

Establish a dynamic prompt. See Prompts, for more information on prompts.

The prompt will be pushed on the dynamic stack. The normal control flow should ensure that the prompt is popped off at the end, via unwind.

If an abort is made to this prompt, control will jump to offset, a three-byte relative address. The continuation and all arguments to the abort will be pushed on the stack, along with the total number of arguments (including the continuation. If control returns to the handler, the prompt is already popped off by the abort mechanism. (Guile’s prompt implements Felleisen’s –F– operator.)

If escape-only? is nonzero, the prompt will be marked as escape-only, which allows an abort to this prompt to avoid reifying the continuation.

Instruction: abort n

Abort to a dynamic prompt.

This instruction pops one tail argument list, n arguments, and a prompt tag from the stack. The dynamic environment is then searched for a prompt having the given tag. If none is found, an error is signalled. Otherwise all arguments are passed to the prompt’s handler, along with the captured continuation, if necessary.

If the prompt’s handler can be proven to not reference the captured continuation, no continuation is allocated. This decision happens dynamically, at run-time; the general case is that the continuation may be captured, and thus resumed. A reinstated continuation will have its arguments pushed on the stack, along with the number of arguments, as in the multiple-value return convention. Therefore an abort instruction should be followed by code ready to handle the equivalent of a multiply-valued return.