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.1 Lexical Environment Instructions

These instructions access and mutate the lexical environment of a compiled procedure—its free and bound variables.

Some of these instructions have long- variants, the difference being that they take 16-bit arguments, encoded in big-endianness, instead of the normal 8-bit range.

See Stack Layout, for more information on the format of stack frames.

Instruction: local-ref index

Instruction: long-local-ref index

Push onto the stack the value of the local variable located at index within the current stack frame.

Note that arguments and local variables are all in one block. Thus the first argument, if any, is at index 0, and local bindings follow the arguments.

Instruction: local-set index

Instruction: long-local-set index

Pop the Scheme object located on top of the stack and make it the new value of the local variable located at index within the current stack frame.

Instruction: box index

Pop a value off the stack, and set the indexnth local variable to a box containing that value. A shortcut for make-variable then local-set, used when binding boxed variables.

Instruction: empty-box index

Set the indexth local variable to a box containing a variable whose value is unbound. Used when compiling some letrec expressions.

Instruction: local-boxed-ref index

Instruction: local-boxed-set index

Get or set the value of the variable located at index within the current stack frame. A shortcut for local-ref then variable-ref or variable-set, respectively.

Instruction: free-ref index

Push the value of the captured variable located at position index within the program’s vector of captured variables.

Instruction: free-boxed-ref index

Instruction: free-boxed-set index

Get or set a boxed free variable. A shortcut for free-ref then variable-ref or variable-set, respectively.

Note that there is no free-set instruction, as variables that are set! must be boxed.

Instruction: make-closure num-free-vars

Pop num-free-vars values and a program object off the stack in that order, and push a new program object closing over the given free variables. num-free-vars is encoded as a two-byte big-endian value.

The free variables are stored in an array, inline to the new program object, in the order that they were on the stack (not the order they are popped off). The new closure shares state with the original program. At the time of this writing, the space overhead of closures is 3 words, plus one word for each free variable.

Instruction: fix-closure index

Fix up the free variables array of the closure stored in the indexth local variable. index is a two-byte big-endian integer.

This instruction will pop as many values from the stack as are in the corresponding closure’s free variables array. The topmost value on the stack will be stored as the closure’s last free variable, with other values filling in free variable slots in order.

fix-closure is part of a hack for allocating mutually recursive procedures. The hack is to store the procedures in their corresponding local variable slots, with space already allocated for free variables. Then once they are all in place, this instruction fixes up their procedures’ free variable bindings in place. This allows most letrec-bound procedures to be allocated unboxed on the stack.

Instruction: local-bound? index

Instruction: long-local-bound? index

Push #t on the stack if the indexth local variable has been assigned, or #f otherwise. Mostly useful for handling optional arguments in procedure prologues.