3.2 Making declarations

3.2.8 OPTIMIZE declarations

Anoptimize declaration controls the type and amount of optimization you want the Compiler to perform. In particular,optimize proclamations select either the development mode or the production mode of the Compiler. You can adjust the following classes of optimizations:

speed
the speed at which compiled code runs

safety
the amount of error checking retained in the compiled code

space
the amount of space that the compiled code needs

compilation-speed

the speed at which the code is compiled

You can adjust the amount of optimization by assigning each class an integer value between 0 and 3 inclusive that represents the level of optimization. To locally assign a value to an optimization class, use anoptimize declaration, as shown in the following example:

(declare (optimize (speed 2) (safety 1)))
To globally assign a value, use a proclamation. Specifying an optimization class without an integer value assigns the highest possible value to the class. The following code globally assignssafety the value 3:

(proclaim '(optimize safety))
By default, the Compiler is set to development mode. To select production mode, you must use an optimization proclamation to setcompilation-speed to 0. To allow the Compiler to fully optimize the code, use the following optimization proclamation:

(proclaim '(optimize (compilation-speed 0) (safety 1) (speed 3)))
The levels of an optimization class are cumulative; each level includes the effects of the previous levels. The optimization classes and their values are as follows:

This class controls the speed at which your compiled code runs. Increasing the level of this class increases the speed of your compiled code but decreases the ease with which you can debug the code. Thus, you should use this class to increase the running speed of your code only after you have completely debugged your code. This class can have the following values:

3
Allows the Compiler to use all optimizations that increase the running speed of compiled code.

2
Turns off tail merging, which decreases the speed of the code but allows frames for tail calls to appear normally on the stack (see Section 3.4.1 on page 57 for an explanation of tail calls and tail merging). This is the default value.

1
Turns off variable elimination and other optimizations that affect the evaluation order of expressions. All user-defined variables appear in stack frames, and function calls are evaluated in their original order. This value includes the effect of the previous values.

0
Turns off in-line coding. Function calls can be traced, and redefinitions affect compiled code. This value includes the effects of the previous values; it retains the most debugging information.

This class controls the amount of error-checking code that is inserted in the compiled code. Lisp uses error-checking code internally to check the numbers and types of the arguments to predefined functions at run-time; safety does not refer to error-handling code that is user written.

Increasing this level increases the amount of error checking in compiled code. This class can have the following values:

0
Inserts no error-checking code in the compiled code.

1
For all platforms except SGI, adds checking on entry for functions with a fixed number of arguments to verify the number of arguments. For SGI, inserts no error-checking code in the compiled code.

2
Adds checking for write-access operations as follows:

Type checking is added for the functionsrplaca,rplacd, andset. In addition, type checking is added for structure accessor functions that are used as arguments tosetf. The accessor functions arecar,cdr,symbol-value,symbol-function,symbol-package,symbol-name,symbol-plist, andmacro-function.

Checking is added for structure accessor functions that are used as arguments tosetf to verify that their arguments are structures and that the offset is within range.

Checking is added for array reference functions that are used as arguments tosetf to verify that their arguments are of the correct type, are within bounds, and are within the offset range. The array reference functions aresvref,aref,char,schar,bit, andsbit.

3
Adds type checking for the read-access operations corresponding to the access operations previously described. In addition, type declarations are ignored, which means that generic operators are not replaced by specific operators. This is the default value.

This class controls the size of the compiled code. Increasing the level decreases the size of the compiled code. This class can have the following values:

0
This value has no effect on the size of the compiled code. This is the default value.

3
This value can decrease the size of compiled code by turning off in-line coding of safe access functions.

This class controls the amount of time required to compile a file. Increasing the level speeds up compilation time. This class can have the following values:

0
This value selects the production mode of the Compiler and should be used when you are ready to produce fully optimized code.

3
This value selects the development mode of the Compiler and should be used when you are developing code. This is the default value.

Table 3.1 summarizes the optimization classes and their default values.

Optimization classes
Class ValueCompiler Action
speed3Allows all optimizations.
 2Turns off tail merging. This is the default.
 1Turns off evaluation reordering.
 0Turns off in-line coding.
safety0Adds no error-checking code.
 1SGI: adds no error-checking code. All others: checks number of arguments on entry to a function with a fixed number of arguments.
 2Checks write access and number of arguments on entry.
 3Checks read access, write access, and number of arguments on entry. This is the default.
space0Imposes no space constraints. This is the default.
 3Turns off in-line coding of safe accessors.
compilation-speed0Selects production mode.
 3Selects development mode. This is the default.

To adjust the level of optimization, you can also specify the keyword arguments:fast-entry,:write-safety,:read-safety,:tail-merge, and:notinline to the functionscompile,compile-file, orcompiler-options. These keyword arguments are extensions to Common Lisp.

Using an optimize declaration to set the value of a class implies that the value of the equivalent keyword argument ist. Table 3.2, Table 3.3, and Table 3.4 show for each platform the relationship between thesafety optimization class and the equivalent keyword settings.

Safety declarations and equivalent keyword settings (SunOS, Solaris, HP)
safety:fast-entry:write:read
0tnilnil
1tnilnil
2niltnil
3niltt

Safety declarations and equivalent keyword settings (RS6000)
safety:fast-entry:write-safety:read-safety
0tnilnil
1tnilnil
2niltnil
3niltt

Safety declarations and equivalent keyword settings (SGI)
safety:write-safety:read-safety
0nilnil
1nilnil
2tnil
3tt

Table 3.5 shows the relationship between thespeed optimization class and the equivalent keyword settings.

Speed declarations and equivalent keyword settings
speed:tail-merge:notinline
0nilt
3tnil

Setting a keyword argument overrides the declaration setting:

;;; Turn off in-line coding.
(proclaim '(optimize (speed 0)))

;;; Override the first proclamation by locally turning off ;;; on in-line coding during the compilation of TEST. (compile 'test nil :notinline nil)

;;; Override the first proclamation by globally turning on ;;; in-line coding. (compiler-options :notinline nil)


The Advanced User's Guide - 9 SEP 1996

Generated with Harlequin WebMaker