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.

Next: , Previous: , Up: Instruction Set   [Contents][Index] Top-Level Environment Instructions

These instructions access values in the top-level environment: bindings that were not lexically apparent at the time that the code in question was compiled.

The location in which a toplevel binding is stored can be looked up once and cached for later. The binding itself may change over time, but its location will stay constant.

Currently only toplevel references within procedures are cached, as only procedures have a place to cache them, in their object tables.

Instruction: toplevel-ref index
Instruction: long-toplevel-ref index

Push the value of the toplevel binding whose location is stored in at position index in the current procedure’s object table. The long- variant encodes the index over two bytes.

Initially, a cell in a procedure’s object table that is used by toplevel-ref is initialized to one of two forms. The normal case is that the cell holds a symbol, whose binding will be looked up relative to the module that was current when the current program was created.

Alternately, the lookup may be performed relative to a particular module, determined at compile-time (e.g. via @ or @@). In that case, the cell in the object table holds a list: (modname sym public?). The symbol sym will be looked up in the module named modname (a list of symbols). The lookup will be performed against the module’s public interface, unless public? is #f, which it is for example when compiling @@.

In any case, if the symbol is unbound, an error is signalled. Otherwise the initial form is replaced with the looked-up variable, an in-place mutation of the object table. This mechanism provides for lazy variable resolution, and an important cached fast-path once the variable has been successfully resolved.

This instruction pushes the value of the variable onto the stack.

Instruction: toplevel-set index
Instruction: long-toplevel-set index

Pop a value off the stack, and set it as the value of the toplevel variable stored at index in the object table. If the variable has not yet been looked up, we do the lookup as in toplevel-ref.

Instruction: define

Pop a symbol and a value from the stack, in that order. Look up its binding in the current toplevel environment, creating the binding if necessary. Set the variable to the value.

Instruction: link-now

Pop a value, x, from the stack. Look up the binding for x, according to the rules for toplevel-ref, and push that variable on the stack. If the lookup fails, an error will be signalled.

This instruction is mostly used when loading programs, because it can do toplevel variable lookups without an object table.

Instruction: variable-ref

Dereference the variable object which is on top of the stack and replace it by the value of the variable it represents.

Instruction: variable-set

Pop off two objects from the stack, a variable and a value, and set the variable to the value.

Instruction: variable-bound?

Pop off the variable object from top of the stack and push #t if it is bound, or #f otherwise. Mostly useful in procedure prologues for defining default values for boxed optional variables.

Instruction: make-variable

Replace the top object on the stack with a variable containing it. Used in some circumstances when compiling letrec expressions.

Next: , Previous: , Up: Instruction Set   [Contents][Index]