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: Procedure Call and Return Instructions, Previous: Lexical Environment Instructions, Up: Instruction Set [Contents][Index]
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.
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.
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.
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.
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.
Dereference the variable object which is on top of the stack and replace it by the value of the variable it represents.
Pop off two objects from the stack, a variable and a value, and set the variable to the value.
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.
Replace the top object on the stack with a variable containing it.
Used in some circumstances when compiling letrec expressions.
Next: Procedure Call and Return Instructions, Previous: Lexical Environment Instructions, Up: Instruction Set [Contents][Index]