3 Optimizing Lisp Programs

3.8 Reference pages

compile Function

Syntax:compile function-or-method&optional function-definition&rest compiler-options

The functioncompile compiles an interpreted function or method in the current Lisp environment and replaces the interpreted function or method definition with the compiled version. For interpreted functions,compile produces a compiled function object from a lambda expression. The lambda expression is the argument function-definition if it is present; otherwise, the function definition of the symbol function-or-method is the relevant lambda expression.

The function-or-method argument tocompile specifies a function name, a method object, or the name of a method to be compiled.

If the function-or-method argument is a function name, the function definition of the symbol function-or-method is set to the compiled function object, andcompile returns that symbol. If the function-or-method argument isnil and the optional function-definition argument is supplied,compile returns the function object.

If the function-or-method argument is a method object or a method name,compile compiles the specified method and returns the method name.

A method name has the following form:

(method generic-function-name {qualifiers}* ({specializer-name}*))

The compiler-options arguments can be any of the keyword-value pairs supplied to the functioncompiler-options. These keyword arguments affect only the specified compilation. The keyword arguments are extensions to Common Lisp.

> (defun double (x) (+ x x))
DOUBLE

> (compile 'double) DOUBLE

> (double 2) 4

> (funcall (compile nil '(lambda (x) (+ x x))) 3) 6

;;; Define the method ADD-ONE and create its associated ;;; generic function. > (defmethod add-one ((x number)) (+ x 1)) #<Standard-Method ADD-ONE (NUMBER)>

> (compile '(method add-one (number))) (METHOD ADD-ONE (NUMBER))

> (add-one 5) 6

See Also: compile-file, compiler-options, uncompile

compile-file Function

Syntax:compile-file input-pathname&key :output-file &rest compiler-options

The functioncompile-file produces binary files from Lisp source files. The compiled functions contained in the binary files become available for use when the binary files are loaded into Lisp.

The function converts the code in the file specified by the input-pa1thname argument into compiled code. It searches for the source file as follows:

The:output-file keyword argument controls where the compiled code is written. If this option is not specified or if its value isnil, the name of the output file is the pathname specified by the input-pathname argument with the following exception: the type component is taken from the first element of the list stored in the variable*load-binary-pathname-types*; the initial value of this element is ("lbin").

If this option is specified, its keyword argument should be a pathname or a string describing a valid filename. If the specified pathname does not include a type component, the type component is taken from the first element of the variable *load-binary-pathname-types*.

The default value of:output-file isnil.

The compiler-options arguments can be any of the keyword-value pairs supplied to the functioncompiler-options. These keyword arguments affect only the specified compilation.

See Also: compile, compiler-options, load, *load-binary-pathname-types*

compiled-function-p Function

Syntax:compiled-function-p object

The predicatecompiled-function-p is true if its argument is a compiled function object; otherwise, it is false.

> (compiled-function-p (symbol-function 'append))
T

> (compiled-function-p #'(lambda (x) x)) NIL

compiler-options Function

Syntax:compiler-options &key :messages :file-messages :optimizep-message :warnings :undef-warnings :show-optimizations :fast-entry :write-safety :read-safety :tail-merge :notinline :egc

The functioncompiler-options sets the default values of the keyword arguments to the functionscompile andcompile-file.

You can specify the following keyword arguments tocompiler-options:

This keyword argument controls Compiler messages. A value oft sends messages to the standard output stream; otherwise, the value must specify a stream to which messages can be sent. The initial value is nil, which suppresses Compiler messages.

This keyword argument controls Compiler file messages. These messages include"Reading source file...","Writing binary file...", and messages that give the current settings forspeed,safety, space, andcompilation-speed. A value ofnil means issue no file messages; otherwise, the value should specify a stream to which messages can be sent. The initial value ist, which sends the messages to the standard output stream.

This keyword argument controls optimization mode messages, which tell you whether you are using the production mode or the development mode of the Compiler. A value ofnil suppresses mode messages. A value of:terse allows terse messages. The initial value ist, which allows full optimization mode messages.

This keyword argument controls the warnings issued by the Compiler. A value ofnil means issue no warnings; otherwise, the value must be either t or a stream to which warnings can be sent. The initial value ist, which sends the warnings to the stream that is the value of the Common Lisp variable *error-output*.

This keyword argument controls the Compiler warnings about undefined function references. A value ofnil suppresses warnings. The initial value ist.

This keyword argument controls optimization reporting, which indicates the success or failure of optimization attempts. A non-nil value shows optimization reports. The value:failure-only causes the Compiler to report only those optimizations that failed. The initial value isnil.

In LCL/SGI, this keyword argument has no effect, since argument checking does not increase the time required to perform a function call. On all other platforms, this keyword argument controls checking the number of arguments on entry to a function with a fixed number of arguments.

A non-nil value means the Compiler does not insert checking in the compiled code; calls to functions compiled in this manner are slightly faster. Settingsafety to 0 has the same effect on fast entry as setting:fast-entry tot. The initial value of:fast-entry isnil.

This keyword argument controls checking for write-access operations. A non-nil value means the Compiler adds checking. Settingsafety to 2 has the same effect on write access as setting:write-safety tot. The initial value of:write-safety ist.

This keyword argument controls checking for read-access operations. A non-nil value means the Compiler adds checking. Settingsafety to 3 has the same effect on read access as setting:read-safety tot. The initial value of:read-safety ist.

This keyword argument controls tail merging. A non-nil value causes the Compiler to convert tail-recursive calls to iterative constructions and to perform other types of tail call optimizations, such as tail merging, that eliminate the overhead of some function calls. Settingspeed to 3 has the same effect on tail merging as setting:tail-merge tot. The initial value of:tail-merge isnil.

If this keyword argument has a non-nil value, the Compiler behaves as if all functions have been declarednotinline; the compiled code uses procedure calls to functions rather than the machine-language code for the functions. Settingspeed to 0 has the same effect on in-line calls as setting:notinline tot. The initial value of:notinline isnil.

If this keyword argument has a non-nil value, the Compiler produces code that can be executed when ephemeral garbage collection is on. If the value isnil, the Compiler produces code that is incompatible with ephemeral garbage collection. Attempting to run such code when ephemeral garbage collection is already turned on signals a continuable error. The initial value of:egc ist. See Chapter 5, "Storage Management in Common Lisp" in The User's Guide for more information about ephemeral garbage collection.

LCL/SGI takes an additional keyword argument,:target.

This keyword argument causes the Compiler to generate code for a specific type of MIPS processor. It can have one of the following values:

  • mips-little-endian

This value causes the Compiler to generate binary files that run only on machines with little-endian byte ordering.

  • mips-big-endian

This value causes the Compiler to generate binary files that run only on machines with big-endian byte ordering. This is the initial value of the:target option.

  • mips

This value causes the Compiler to generate binary code that can run on machines with either little-endian or big-endian byte ordering. Binary files produced with this target can be loaded into either machine type. Certain operations, such as accessing floating-point arrays, will run more slowly.

See Also:compile, compile-file

declare Special Form

Syntax:declare {decl-spec}*

decl-spec::= (special {var}*)
| (type type-specifier {var}*)
| (type-specifier {var}*)
| (ftype type-specifier {function-name}*)
| (function function-name ({type-specifier}*) {type-specifier}*
| (restrictive-ftype type-specifier {function-name}*)
| (type-reduce type1 type2)
| (inline {function-name}*)
| (notinline {function-name}*)
| (ignore {var}*)
| (optimize {(quality value) | quality}*)
| (declaration {declaration-name}*)
| (arglist declared-arguments)
| (dynamic-extent variable)

quality::=speed |space |safety |compilation-speed

value::= 0 | 1 | 2 | 3

Thedeclare special form makes declarations within certain forms. Declarations can occur in lambda expressions and in the following forms:

defgeneric
define-setf-method
defmacro
defmethod
defsetf
deftype
defun
do
do*
do-all-symbols
do-external-symbols
do-symbols
dolist
dotimes
flet
labels
let
let*
locally
macrolet
multiple-value-bind
prog
prog*
with-input-from-string
with-open-file
with-open-stream
with-output-to-string
with-output-to-string

Declarations can only occur where specified by the syntax of these forms. Macros can expand into declarations as long as this syntax is observed.

The declaration specifier argument is not evaluated.

> (defun example (y)                   ; This y is regarded
    (declare (special y))              ; as special.
    (let ((y t))                       ; This y is regarded
      (list y                          ; as lexical.
       (locally (declare (special y)) y)))) ; This y refers to the
                                       ; special binding of y.
EXAMPLE

> (example nil) (T NIL)

See Also: locally, def-compiler-macro

def-compiler-macro Macro

Syntax:def-compiler-macro name lambda-list {form}*

The macrodef-compiler-macro defines a Compiler macro. A Compiler macro is a macro that affects only compiled code, not interpreted code.

The name argument is a symbol; it is not evaluated. A global Compiler macro expansion function is associated with the symbol name. It is possible to have a Compiler macro defined withdef-compiler-macro associated with the same name as a function defined withdefun or a macro defined withdefmacro. During compilation, thedef-compiler-macro definitions override defun anddefmacro definitions.

The name is returned as the result ofdef-compiler-macro.

The lambda-list argument specifies the arguments to the macro being defined; this argument is equivalent to a lambda list of a defmacro form.

The body of the macro expansion function is specified by the form arguments. They are executed in order.

> (defmacro xx1 (x) '(format nil "~A interpreted" ,x)) 
XX1

> (def-compiler-macro xx1 (x) '(format nil "~A compiled" ,x)) XX1

> (defun xx2 () (xx1 "test is")) XX2

> (xx2) "test is interpreted"

> (compile 'xx2) XX2

> (xx2) "test is compiled"

See Also: undef-compiler-macro;defmacro (in CLtL2)

defsubst Function

Syntax:defsubst name lambda-list {form}*

The functiondefsubst defines a function and makes its definition available for in-line expansion by the Compiler.

The name argument must be a symbol; it is not evaluated. A global function definition is attached to the symbol name as the contents of the symbol's function cell. The name of the new function is returned as the value of thedefsubst form.

The lambda-list argument specifies the arguments to the function being defined.

The body of the function consists of the forms specified by the form arguments; they are executed in order when the function is called.

The expression (defsubst new-function ...) is equivalent to the following expression:

(progn (proclaim '(inline new-function)) (defun new-function ...))
When a call to a function defined withdefsubst has been compiled, it cannot be traced or redefined.

> (defsubst test1 () "This is a test")
TEST1

> (defun test2 () (test1)) TEST2

> (trace test1) (TEST1)

> (test2) 1 Enter TEST1 1 Exit TEST1 "This is a test" "This is a test"

> (compile 'test2) TEST2

> (test2) "This is a test"

> (untrace test1) (TEST1)

> (defun test1 () "This is a new test") TEST1

> (test2) "This is a test"

See Also: proclaim;defun (in CLtL2)

disassemble Function

Syntax:disassemble name-or-compiled-function

The functiondisassemble disassembles a compiled function and prints the resulting code on the standard output. It returns nil.

If the argument is the name of an interpreted function, that function is first compiled and then disassembled. The function definition that is attached to the name as the content of the symbol's function cell is not changed.

The standard output is defined by the value of the Common Lisp variable*standard-output*.

enable-stack-lists Function

disable-stack-lists Function

Syntax:enable-stack-lists &key :max-depth :max-length

Syntax:disable-stack-lists

These functions control stack list allocation. Stack list allocation allows the Compiler to generate code that allocates&rest arguments declared to have dynamic extent on a stack instead of in dynamic memory. This reduces the number of garbage collections.

The:max-depth keyword argument specifies the maximum number of stack lists that can be allocated at any time. If specified, the value of:max-depth must be an integer between 10 and 10000 inclusive. The default value is 100.

The:max-length keyword argument specifies the maximum number of cons cells that can be allocated in stack lists at any time. If specified, the value of:max-length must be an integer between 100 and 100000. The default value is 1000.

If stack list allocation is repeatedly enabled in a Lisp process, the maximum depth and maximum length are never reduced, even if the:max-depth and:max-length arguments are given smaller values than were previously used.

If the creation of a stack list would exceed either the maximum depth or the maximum length, the list is created in dynamic memory instead.

Stack list allocation is enabled by default. You need only call the functionenable-stack-lists to increase the available stack list space or to reenable stack list allocation after a call to disable-stack-lists.

eval-when Special Form

Syntax:eval-when ({situation}*) {form}*

The special formeval-when specifies when a particular body of code will be executed.

The execution time is defined by the situation arguments. Each argument must have one of the following values:

The value of the last form evaluated is returned as the result ofeval-when. If no forms are executed,eval-when returnsnil.

The form arguments are executed in order.

> (setq test 3)
3

> (eval-when (compile) (setq test 2)) NIL

> test 3

> (eval-when (eval) (setq test 2)) 2

> test 2

locally Macro

Syntax:locally {declaration}* {form}*

Thelocally macro makes local declarations that affect only its form arguments.

> (defun example (y)                   ; This y is regarded
    (declare (special y))              ; as special.
    (let ((y t))                      ; This y is regarded
      (list y                         ; as lexical.
    (locally (declare (special y)) y)))) ; This y refers to the
                                     ; special binding of y.
EXAMPLE

> (example nil) (T NIL)

See Also: declare

proclaim Function

Syntax:proclaim decl-spec

Theproclaim function makes a global declaration, or proclamation.

A proclamation whose declaration specifier declares a variable to bespecial makes all occurrences of that variable name special references.

Although the effect of a proclamation is global, it can be overridden by a local declaration.

The argument ofproclaim is evaluated. It can therefore be a computed declaration specifier.

> (proclaim '(special prosp))
T

> (setq prosp 1 reg 1) 1

> (let ((prosp 2)(reg 2)) (set 'prosp 3)(set 'reg 3) (list prosp reg)) (3 2)

> (list prosp reg) (1 3)

See Also: unproclaim;defvar,defparameter (in CLtL2)

report-compiler-options Function

Syntax:report-compiler-options

The functionreport-compiler-options produces a formatted report of the current values of the keyword arguments to the functionscompile,compile-file, andcompiler-options, as well as the current values of the optimization levels.

See Also: compile, compile-file, compiler-options

reset-compiler-options Function

Syntax:reset-compiler-options

The functionreset-compiler-options sets the values of the keyword arguments to the functionscompile,compile-file, andcompiler-options to their initial values. It does not change the current value of the:target keyword argument (applies to LCL/SGI only).

See Also: compile, compile-file, compiler-options,report-compiler-options

*style-warnings* Variable

Syntax:*style-warnings*

This variable controls the warning messages issued when a variable that is named according to the convention for a global variable is lexically bound without being declared special. If the value of the variable isnil, no warnings are issued. The default value ist.

the Special Form

Syntax:the value-type form

The special formthe specifies that the value produced by a form will be of a certain type.

Thethe special form returns the value or values that result from form.

The value-type argument is a type specifier; it is not evaluated. The form argument is evaluated.

You can use the Common Lisp macrosetf withthe declarations. In this case the declaration is transferred to the form that specified the new value. The resultingsetf form is then used.

> (the list '(a b))
(A B)

> (the (values integer list) (values 5 '(a b))) 5 (A B)

> (let ((i 100)) (declare (fixnum i)) (the fixnum (1+ i))) 101

uncompile Function

Syntax:uncompile function-or-method

The functionuncompile replaces the compiled version of the specified function, macro, or method with its original interpreted definition. The function, macro, or method must have been compiled by a call to the functioncompile; otherwise, an error is signaled.

The function-or-method argument touncompile specifies a function name, a macro name, a method object, or the name of a method. A method name has the following form:

(method generic-function-name {qualifiers}* ({specializer-name}*))

See Also: compile

undef-compiler-macro Macro

Syntax:undef-compiler-macro name

The macroundef-compiler-macro removes a Compiler macro definition.

The name argument is a symbol.

See Also: def-compiler-macro

unproclaim Function

Syntax:unproclaim decl-spec

The functionunproclaim reverses a proclamation.

The decl-spec argument must be a valid declaration specifier fordeclare; otherwise, an error is signaled. With the exception of theoptimize declaration, the declaration specifier must exactly match the most recently proclaimed declaration specifier. If it does not, the call tounproclaim has no effect.

Ifunproclaim is called with a declaration specifier of the form (optimize quality), quality is set to its default value. Ifunproclaim is called with a declaration specifier of the form (optimize (quality value)), quality is reset to its default value only if the current value of quality is value; otherwise, the call has no effect.

See Also: proclaim

with-compiler-options Macro

Syntax:with-compiler-options options&body body

The macrowith-compiler-options evaluates a specified series of forms.

The options arguments can be any of the keyword-value pairs supplied to the functioncompiler-options. The keyword arguments affect only the specified series of forms.

See Also: compiler-options

with-deferred-warnings Macro

Syntax:with-deferred-warnings {form}*

The macrowith-deferred-warnings defers undefined function warnings until the end of the execution of the specified forms.


The Advanced User's Guide - 9 SEP 1996

Generated with Harlequin WebMaker