9.3.6.3 Procedure Call and Return Instructions

Instruction: new-frame

Push a new frame on the stack, reserving space for the dynamic link, return address, and the multiple-values return address. The frame pointer is not yet updated, because the frame is not yet active – it has to be patched by a call instruction to get the return address.

Instruction: call nargs

Call the procedure located at sp[-nargs] with the nargs arguments located from sp[-nargs + 1] to sp[0].

This instruction requires that a new frame be pushed on the stack before the procedure, via new-frame. See section Stack Layout, for more information. It patches up that frame with the current ip as the return address, then dispatches to the first instruction in the called procedure, relying on the called procedure to return one value to the newly-created continuation. Because the new frame pointer will point to sp[-nargs + 1], the arguments don’t have to be shuffled around – they are already in place.

Instruction: tail-call nargs

Transfer control to the procedure located at sp[-nargs] with the nargs arguments located from sp[-nargs + 1] to sp[0].

Unlike call, which requires a new frame to be pushed onto the stack, tail-call simply shuffles down the procedure and arguments to the current stack frame. This instruction implements tail calls as required by RnRS.

Instruction: apply nargs

Instruction: tail-apply nargs

Like call and tail-call, except that the top item on the stack must be a list. The elements of that list are then pushed on the stack and treated as additional arguments, replacing the list itself, then the procedure is invoked as usual.

Instruction: call/nargs

Instruction: tail-call/nargs

These are like call and tail-call, except they take the number of arguments from the stack instead of the instruction stream. These instructions are used in the implementation of multiple value returns, where the actual number of values is pushed on the stack.

Instruction: mv-call nargs offset

Like call, except that a multiple-value continuation is created in addition to a single-value continuation.

The offset (a three-byte value) is an offset within the instruction stream; the multiple-value return address in the new frame (see section Stack Layout) will be set to the normal return address plus this offset. Instructions at that offset will expect the top value of the stack to be the number of values, and below that values themselves, pushed separately.

Instruction: return

Free the program’s frame, returning the top value from the stack to the current continuation. (The stack should have exactly one value on it.)

Specifically, the sp is decremented to one below the current fp, the ip is reset to the current return address, the fp is reset to the value of the current dynamic link, and then the returned value is pushed on the stack.

Instruction: return/values nvalues

Instruction: return/nvalues

Return the top nvalues to the current continuation. In the case of return/nvalues, nvalues itself is first popped from the top of the stack.

If the current continuation is a multiple-value continuation, return/values pushes the number of values on the stack, then returns as in return, but to the multiple-value return address.

Otherwise if the current continuation accepts only one value, i.e. the multiple-value return address is NULL, then we assume the user only wants one value, and we give them the first one. If there are no values, an error is signaled.

Instruction: return/values* nvalues

Like a combination of apply and return/values, in which the top value on the stack is interpreted as a list of additional values. This is an optimization for the common (apply values ...) case.

Instruction: truncate-values nbinds nrest

Used in multiple-value continuations, this instruction takes the values that are on the stack (including the number-of-values marker) and truncates them for a binding construct.

For example, a call to (receive (x y . z) (foo) ...) would, logically speaking, pop off the values returned from (foo) and push them as three values, corresponding to x, y, and z. In that case, nbinds would be 3, and nrest would be 1 (to indicate that one of the bindings was a rest argument).

Signals an error if there is an insufficient number of values.

Instruction: call/cc

Instruction: tail-call/cc

Capture the current continuation, and then call (or tail-call) the procedure on the top of the stack, with the continuation as the argument.

call/cc does not require a new-frame to be pushed on the stack, as call does, because it needs to capture the stack before the frame is pushed.

Both the VM continuation and the C continuation are captured.

This document was generated on April 20, 2013 using texi2html 5.0.