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.

6.9.3 Compiled Procedures

The evaluation strategy given in Lambda describes how procedures are interpreted. Interpretation operates directly on expanded Scheme source code, recursively calling the evaluator to obtain the value of nested expressions.

Most procedures are compiled, however. This means that Guile has done some pre-computation on the procedure, to determine what it will need to do each time the procedure runs. Compiled procedures run faster than interpreted procedures.

Loading files is the normal way that compiled procedures come to being. If Guile sees that a file is uncompiled, or that its compiled file is out of date, it will attempt to compile the file when it is loaded, and save the result to disk. Procedures can be compiled at runtime as well. See Read/Load/Eval/Compile, for more information on runtime compilation.

Compiled procedures, also known as programs, respond all procedures that operate on procedures. In addition, there are a few more accessors for low-level details on programs.

Most people won’t need to use the routines described in this section, but it’s good to have them documented. You’ll have to include the appropriate module first, though:

(use-modules (system vm program))

Scheme Procedure: program? obj

C Function: scm_program_p (obj)

Returns #t if obj is a compiled procedure, or #f otherwise.

Scheme Procedure: program-objcode program

C Function: scm_program_objcode (program)

Returns the object code associated with this program. See Bytecode and Objcode, for more information.

Scheme Procedure: program-objects program

C Function: scm_program_objects (program)

Returns the “object table” associated with this program, as a vector. See VM Programs, for more information.

Scheme Procedure: program-module program

C Function: scm_program_module (program)

Returns the module that was current when this program was created. Can return #f if the compiler could determine that this information was unnecessary.

Scheme Procedure: program-free-variables program

C Function: scm_program_free_variables (program)

Returns the set of free variables that this program captures in its closure, as a vector. If a closure is code with data, you can get the code from program-objcode, and the data via program-free-variables.

Some of the values captured are actually in variable “boxes”. See Variables and the VM, for more information.

Users must not modify the returned value unless they think they’re really clever.

Scheme Procedure: program-meta program

C Function: scm_program_meta (program)

Return the metadata thunk of program, or #f if it has no metadata.

When called, a metadata thunk returns a list of the following form: (bindings sources arities . properties). The format of each of these elements is discussed below.

Scheme Procedure: program-bindings program

Scheme Procedure: make-binding name boxed? index start end

Scheme Procedure: binding:name binding

Scheme Procedure: binding:boxed? binding

Scheme Procedure: binding:index binding

Scheme Procedure: binding:start binding

Scheme Procedure: binding:end binding

Bindings annotations for programs, along with their accessors.

Bindings declare names and liveness extents for block-local variables. The best way to see what these are is to play around with them at a REPL. See VM Concepts, for more information.

Note that bindings information is stored in a program as part of its metadata thunk, so including it in the generated object code does not impose a runtime performance penalty.

Scheme Procedure: program-sources program

Scheme Procedure: source:addr source

Scheme Procedure: source:line source

Scheme Procedure: source:column source

Scheme Procedure: source:file source

Source location annotations for programs, along with their accessors.

Source location information propagates through the compiler and ends up being serialized to the program’s metadata. This information is keyed by the offset of the instruction pointer within the object code of the program. Specifically, it is keyed on the ip just following an instruction, so that backtraces can find the source location of a call that is in progress.

Scheme Procedure: program-arities program

C Function: scm_program_arities (program)

Scheme Procedure: program-arity program ip

Scheme Procedure: arity:start arity

Scheme Procedure: arity:end arity

Scheme Procedure: arity:nreq arity

Scheme Procedure: arity:nopt arity

Scheme Procedure: arity:rest? arity

Scheme Procedure: arity:kw arity

Scheme Procedure: arity:allow-other-keys? arity

Accessors for a representation of the “arity” of a program.

The normal case is that a procedure has one arity. For example, (lambda (x) x), takes one required argument, and that’s it. One could access that number of required arguments via (arity:nreq (program-arities (lambda (x) x))). Similarly, arity:nopt gets the number of optional arguments, and arity:rest? returns a true value if the procedure has a rest arg.

arity:kw returns a list of (kw . idx) pairs, if the procedure has keyword arguments. The idx refers to the idxth local variable; See Variables and the VM, for more information. Finally arity:allow-other-keys? returns a true value if other keys are allowed. See Optional Arguments, for more information.

So what about arity:start and arity:end, then? They return the range of bytes in the program’s bytecode for which a given arity is valid. You see, a procedure can actually have more than one arity. The question, “what is a procedure’s arity” only really makes sense at certain points in the program, delimited by these arity:start and arity:end values.

Scheme Procedure: program-arguments-alist program [ip]

Return an association list describing the arguments that program accepts, or #f if the information cannot be obtained.

The alist keys that are currently defined are ‘required’, ‘optional’, ‘keyword’, ‘allow-other-keys?’, and ‘rest’. For example:

(program-arguments-alist
 (lambda* (a b #:optional c #:key (d 1) #:rest e)
   #t)) ⇒
((required . (a b))
 (optional . (c))
 (keyword . ((#:d . 4)))
 (allow-other-keys? . #f)
 (rest . d))

Scheme Procedure: program-lambda-list program [ip]

Return a representation of the arguments of program as a lambda list, or #f if this information is not available.

For example:

(program-lambda-list
 (lambda* (a b #:optional c #:key (d 1) #:rest e)
   #t)) ⇒