CMUCL User’s Manual

2.1.1 Integers

The fixnum type is equivalent to (signed-byte 30). Integers outside this range are represented as a bignum or a word integer (see word-integers.) Almost all integers that appear in programs can be represented as a fixnum, so integer number consing is rare.

2.1.2 Floats

CMUCL supports three floating point formats: single-float, double-float and double-double-float. The first two are implemented with IEEE single and double float arithmetic, respectively. The last is an extension; see extended-float for more information. short-float is a synonym for single-float, and long-float is a synonym for double-float. The initial value of read-default-float-format is single-float.

Both single-float and double-float are represented with a pointer descriptor, so float operations can cause number consing. Number consing is greatly reduced if programs are written to allow the use of non-descriptor representations (see numeric-types.)

• IEEE Special Values
• Negative Zero
• Denormalized Floats
• Floating Point Exceptions
• Floating Point Rounding Mode
• Accessing the Floating Point Modes

2.1.3 Extended Floats

CMUCL also has an extension to support double-double-float type. This float format provides extended precision of about 31 decimal digits, with the same exponent range as double-float. It is completely integrated into CMUCL, and can be used just like any other floating-point object, including arrays, complex double-double-float’s, and special functions. With appropriate declarations, no boxing is needed, just like single-float and double-float.

The exponent marker for a double-double float number is “W”, so “1.234w0” is a double-double float number.

Note that there are a few shortcomings with double-double-float’s:

• There are no equivalents to most-positive-double-float, double-float-positive-infinity, etc. This is because these are not really well defined for double-double-float’s.
• Underflow and overflow may be prematurely signaled. This is due to how double-double-float’s are implemented.
• Basic arithmetic operations are inlined, so the code size is fairly large.
• double-double-float arithmetic is quite a bit slower than double-float since there is no hardware support for this type.
• The constant pi is still a double-float instead of a double-double-float. Use ext:dd-pi if you want a double-double-float value for \pi.

float: extensions:double-double-float ¶

The double-double-float type. It is in the EXTENSIONS package.

Constant: extensions:dd-pi ¶

A double-double-float approximation to \pi.

2.1.4 Characters

CMUCL implements characters according to Common Lisp: The Language II. The main difference from the first version is that character bits and font have been eliminated, and the names of the types have been changed. base-character is the new equivalent of the old string-char. In this implementation, all characters are base characters (there are no extended characters).

If (featurep :unicode) is false, then character codes range between 0 and 255, using the ASCII encoding. Otherwise, Unicode is supported and character codes corresond to utf-16 code units. See i18n for further information.

Table 2.1 shows characters recognized by CMUCL.

When Unicode support is available, additional character names are supported. If the Unicode character has a name, such as “GREEK SMALL LETTER ALPHA”, you may use #\greek_small_letter_alpha to create the Greek character alpha whose code point value is #x3b1. Alternatively, you can specify a character using the hex value of the code point. Hence #\u+3b1 produces the same character. The u+ is required for hex values.

2.1.5 Array Initialization

If no :initial-value is specified, arrays are initialized to zero.

2.1.6 Hash tables

The hash-tables defined by Common Lisp have limited utility because they are limited to testing their keys using the equality predicates provided by (pre-CLOS) Common Lisp. CMUCL overcomes this limitation by allowing its users to specify new hash table tests and hashing methods. The hashing method must also be specified, since the compiler is unable to determine a good hashing function for an arbitrary equality (equivalence) predicate.

Function: extensions:define-hash-table-test hash-table-test-name test-function hash-function ¶

The hash-table-test-name must be a symbol. The test-function takes two objects and returns true iff they are the same. The hash-function takes one object and returns two values: the (positive fixnum) hash value and true if the hashing depends on pointer values and will have to be redone if the object moves.

To create a hash-table using this new “test” (really, a test/hash-function pair), use (make-hash-table :test hash-table-test-name ...).

Note that it is the hash-table-test-name that will be returned by the function hash-table-test, when applied to a hash-table created using this function.

This function updates hash-table-tests, which is now internal.

CMUCL also supports a number of weak hash tables. These weak tables are created using the :weak-p argument to make-hash-table. Normally, a reference to an object as either the key or value of the hash-table will prevent that object from being garbage-collected. However, in a weak table, if the only reference is the hash-table, the object can be collected.

The possible values for :weak-p are listed below. An entry in the table remains if the condition holds

:key

The key is referenced elsewhere

:value

The value is referenced elsewhere

:key-and-value

Both the key and value are referenced elsewhere

:key-or-value

Either the key or value are referenced elsewhere

T

For backward compatibility, this means the same as :key.

If the condition does not hold, the object can be removed from the hash table.

Weak hash tables can only be created if the test is eq or eql. An error is signaled if this is not the case.

Function: make-hash-table &key :test :size :rehash-size :rehash-threshold :weak-p ¶

Creates a hash-table with the specified properties.

2.4.1 Introduction

The Common Lisp package system, designed and standardized several years ago, is not hierarchical. Since Common Lisp was standardized, other languages, including Java and Perl, have evolved namespaces which are hierarchical. This document describes a hierarchical package naming scheme for Common Lisp. The scheme was proposed by Franz Inc and implemented in their Allegro Common Lisp product; a compatible implementation of the naming scheme is implemented in CMUCL. This documentation is based on the Franz Inc. documentation, and is included with permission.

The goals of hierarchical packages in Common Lisp are:

• Reduce collisions with user-defined packages: it is a well-known problem that package names used by the Lisp implementation and those defined by users can easily conflict. The intent of hierarchical packages is to reduce such conflicts to a minimum.
• Improve modularity: the current organization of packages in various implementations has grown over the years and appears somewhat random. Organizing future packages into a hierarchy will help make the intention of the implementation more clear.
• Foster growth in Common Lisp programs, or modules, available to the CL community: the Perl and Java communities are able to contribute code to repositories, with minimal fear of collision, because of the hierarchical nature of the name spaces used by the contributed code. We want the Lisp community to benefit from shared modules in the same way.

In a nutshell, a dot (.) is used to separate levels in package names, and a leading dot signifies a relative package name. The choice of dot follows Java. Perl, another language with hierarchical packages, uses a colon (:) as a delimiter, but the colon is already reserved in Common Lisp. Absolute package names require no modifications to the underlying Common Lisp implementation. Relative package names require only small and simple modifications.

2.4.2 Relative Package Names

Relative package names are needed for the same reason as relative pathnames, for brevity and to reduce the brittleness of absolute names. A relative package name is one that begins with one or more dots. A single dot means the current package, two dots mean the parent of the current package, and so on.

Table 2.2 presents a number of examples, assuming that the packages named foo, foo.bar, mypack, mypack.foo, mypack.foo.bar, mypack.foo.baz, mypack.bar, and mypack.bar.baz, have all been created.

Additional notes:

1. All packages in the hierarchy must exist.
2. Warning about nicknames: Unless you provide nicknames for your hierarchical packages (and we recommend against doing so because the number gets quite large), you can only use the names supplied. You cannot mix in nicknames or alternate names. cl-user is nickname of the common-lisp-user package. Consider the following:

      (defpackage :cl-user.foo)
   

   When the current package (the value of the variable *package*) is common-lisp-user, you might expect .foo to refer to cl-user.foo, but it does not. It actually refers to the non-existent package common-lisp-user.foo. Note that the purpose of nicknames is to provide shorter names in place of the longer names that are designed to be fully descriptive. The hope is that hierarchical packages makes longer names unnecessary and thus makes nicknames unnecessary.

3. Multiple dots can only appear at the beginning of a package name. For example, foo.bar..baz does not mean foo.baz – it is invalid. (Of course, it is perfectly legal to name a package foo.bar..baz, but cl:find-package will not process such a name to find foo.baz in the package hierarchy.)

2.4.3 Compatibility with ANSI Common Lisp

The implementation of hierarchical packages modifies the cl:find-package function, and provides certain auxiliary functions, package-parent, package-children, and relative-package-name-to-package, as described in this section. The function defpackage itself requires no modification.

While the changes to cl:find-package are small and described below, it is an important consideration for authors who would like their programs to run on a variety of implementations that using hierarchical packages will work in an implementation without the modifications discussed in this document. We show why after describing the changes to cl:find-package.

Absolute hierarchical package names require no changes in the underlying Common Lisp implementation.

• Changes to cl:find-package
• Using Hierarchical Packages without Modifying cl:find-package

   (defpackage :my.foo.bar
     #-relative-package-names (:nicknames #:..bar)
     ...)

   (defpackage :my.foo.baz
     #-relative-package-names (:nicknames #:..baz)
     ...)

2.5.1 Rationale

Package locks are an aid to program development, by helping to detect inadvertent name collisions and function redefinitions. They are consistent with the principle that a package “belongs to” its implementor, and that noone other than the package’s developer should be making or modifying definitions on symbols in that package. Package locks are compatible with the ANSI Common Lisp standard, which states that the consequences of redefining functions in the COMMON-LISP package are undefined.

Violation of a package lock leads to a continuable error of type lisp::package-locked-error being signaled. The user may choose to ignore the lock and proceed, or to abort the computation. Two other restarts are available, one which disables all locks on all packages, and one to disable only the package-lock or package-definition-lock that was tripped.

The following transcript illustrates the behaviour seen when attempting to redefine a standard macro in the COMMON-LISP package, or to redefine a function in one of CMUCL’s implementation-defined packages:

CL-USER> (defmacro 1+ (x) (* x 2))
Attempt to modify the locked package COMMON-LISP, by defining macro 1+
   [Condition of type LISP::PACKAGE-LOCKED-ERROR]

Restarts:
  0: [continue      ] Ignore the lock and continue
  1: [unlock-package] Disable the package's definition-lock then continue
  2: [unlock-all    ] Unlock all packages, then continue
  3: [abort         ] Return to Top-Level.

CL-USER> (defun ext:gc () t)
Attempt to modify the locked package EXTENSIONS, by redefining function GC
   [Condition of type LISP::PACKAGE-LOCKED-ERROR]

Restarts:
  0: [continue      ] Ignore the lock and continue
  1: [unlock-package] Disable package's definition-lock, then continue
  2: [unlock-all    ] Disable all package locks, then continue
  3: [abort         ] Return to Top-Level.

The following transcript illustrates the behaviour seen when an attempt to modify the structure of a package is made:

CL-USER> (unexport 'load-foreign :ext)
Attempt to modify the locked package EXTENSIONS, by unexporting symbols LOAD-FOREIGN
   [Condition of type lisp::package-locked-error]

Restarts:
  0: [continue      ] Ignore the lock and continue
  1: [unlock-package] Disable package's lock then continue
  2: [unlock-all    ] Unlock all packages, then continue
  3: [abort         ] Return to Top-Level.

The COMMON-LISP package and the CMUCL-specific implementation packages are locked on startup. Users can lock their own packages by using the ext:package-lock and ext:package-definition-lock accessors.

2.5.2 Disabling package locks

A package’s locks can be enabled or disabled by using the ext:package-lock and ext:package-definition-lock accessors, as follows:

   (setf (ext:package-lock (find-package "UNIX")) nil)
   (setf (ext:package-definition-lock (find-package "UNIX")) nil)

Function: ext:package-lock package ¶

This function is an accessor for a package’s structural lock, which protects it against modifications to its list of exported symbols.

Function: ext:package-definition-lock package ¶

This function is an accessor for a package’s definition-lock, which protects symbols in that package from redefinition. As well as protecting the symbol’s fdefinition from change, attempts to change the symbol’s definition using defstruct, defclass or deftype will be trapped.

Macro: ext:without-package-locks &rest body ¶

This macro can be used to execute forms with all package locks (both structure and definition locks) disabled.

Function: ext:unlock-all-packages ¶

This function disables both structure and definition locks on all currently defined packages. Note that package locks are reset when CMUCL is restarted, so the effect of this function is limited to the current session.

2.7.1 GC Parameters

The following variables control the behavior of the garbage collector:

Variable: extensions:*bytes-consed-between-gcs* ¶

CMUCL automatically GC’s whenever the amount of memory allocated to dynamic objects exceeds the value of an internal variable. After each GC, the system sets this internal variable to the amount of dynamic space in use at that point plus the value of the variable ext:*bytes-consed-between-gcs*. The default value is 2000000.

Variable: extensions:*gc-verbose* ¶

This variable controls whether ext:gc invokes the functions in ext:*gc-notify-before* and ext:*gc-notify-after*. If *gc-verbose* is nil, ext:gc foregoes printing any messages. The default value is T.

Variable: extensions:*gc-notify-before* ¶

This variable’s value is a function that should notify the user that the system is about to GC. It takes one argument, the amount of dynamic space in use before the GC measured in bytes. The default value of this variable is a function that prints a message similar to the following:

   [GC threshold exceeded with 2,107,124 bytes in use.  Commencing GC.]

Variable: extensions:*gc-notify-after* ¶

This variable’s value is a function that should notify the user when a GC finishes. The function must take three arguments, the amount of dynamic spaced retained by the GC, the amount of dynamic space freed, and the new threshold which is the minimum amount of space in use before the next GC will occur. All values are byte quantities. The default value of this variable is a function that prints a message similar to the following:

    [GC completed with 25,680 bytes retained and 2,096,808 bytes freed.]
    [GC will next occur when at least 2,025,680 bytes are in use.]

Note that a garbage collection will not happen at exactly the new threshold printed by the default ext:*gc-notify-after* function. The system periodically checks whether this threshold has been exceeded, and only then does a garbage collection.

Variable: extensions:*gc-inhibit-hook* ¶

This variable’s value is either a function of one argument or nil. When the system has triggered an automatic GC, if this variable is a function, then the system calls the function with the amount of dynamic space currently in use (measured in bytes). If the function returns nil, then the GC occurs; otherwise, the system inhibits automatic GC as if you had called ext:gc-off. The writer of this hook is responsible for knowing when automatic GC has been turned off and for calling or providing a way to call ext:gc-on. The default value of this variable is nil.

Variable: extensions:*before-gc-hooks* ¶

Variable: extensions:*after-gc-hooks* ¶

These variables’ values are lists of functions to call before or after any GC occurs. The system provides these purely for side-effect, and the functions take no arguments.

2.7.2 Generational GC

Generational GC also supports some additional functions and variables to control it.

Function: extensions:gc &key :verbose :gen :full ¶

This function runs the garbage collector. If ext:*gc-verbose* is non-nil, then it invokes ext:*gc-notify-before* before GC’ing and ext:*gc-notify-after* afterwards.

verbose

Print GC statistics if non-NIL.

gen

The number of generations to be collected.

full

If non-NIL, a full collection of all generations is performed.

Function: lisp::gencgc-stats generation ¶

Returns statistics about the generation, as multiple values:

1. Bytes allocated in this generation
2. The GC trigger for this generation. When this many bytes have been allocated, a GC is started automatically.
3. The number of bytes consed between GCs.
4. The number of GCs that have been done on this generation. This is reset to zero when the generation is raised.
5. The trigger age, which is the maximum number of GCs to perform before this generation is raised.
6. The total number of bytes allocated to this generation.
7. Average age of the objects in this generations. The average age is the cumulative bytes allocated divided by current number of bytes allocated.

Function: lisp::set-gc-trigger gen trigger ¶

Sets the GC trigger value for the specified generation.

Function: lisp::set-trigger-age gen trigger-age ¶

Sets the GC trigger age for the specified generation.

Function: lisp::set-min-mem-age gen min-mem-age ¶

Sets the minimum average memory age for the specified generation. If the computed memory age is below this, GC is not performed, which helps prevent a GC when a large number of new live objects have been added in which case a GC would usually be a waste of time.

2.7.3 Weak Pointers

A weak pointer provides a way to maintain a reference to an object without preventing an object from being garbage collected. If the garbage collector discovers that the only pointers to an object are weak pointers, then it breaks the weak pointers and deallocates the object.

Function: extensions:make-weak-pointer object ¶

Function: extensions:weak-pointer-value weak-pointer ¶

make-weak-pointer returns a weak pointer to an object. weak-pointer-value follows a weak pointer, returning the two values: the object pointed to (or nil if broken) and a boolean value which is nil if the pointer has been broken, and true otherwise.

2.7.4 Finalization

Finalization provides a “hook” that is triggered when the garbage collector reclaims an object. It is usually used to recover non-Lisp resources that were allocated to implement the finalized Lisp object. For example, when a unix file-descriptor stream is collected, finalization is used to close the underlying file descriptor.

Function: extensions:finalize object function ¶

This function registers object for finalization. function is called with no arguments when object is reclaimed. Normally function will be a closure over the underlying state that needs to be freed, e.g. the unix file descriptor in the fd-stream case. Note that function must not close over object itself, as this prevents the object from ever becoming garbage.

Function: extensions:cancel-finalization object ¶

This function cancel any finalization request for object.

2.9.1 The Graphical Interface

CMUCL has an interface to Motif which is functionally similar to CLM, but works better in CMUCL. This interface is documented in separate manuals CMUCL Motif Toolkit and Design Notes on the Motif Toolkit, which are distributed with CMUCL.

This motif interface has been used to write the inspector and graphical debugger. There is also a Lisp control panel with a simple file management facility, apropos and inspector dialogs, and controls for setting global options. See the interface and toolkit packages.

Function: interface:lisp-control-panel ¶

This function creates a control panel for the Lisp process.

Variable: interface:*interface-style* ¶

When the graphical interface is loaded, this variable controls whether it is used by inspect and the error system. If the value is :graphics (the default) and the DISPLAY environment variable is defined, the graphical inspector and debugger will be invoked by inspect or when an error is signalled. Possible values are :graphics and :tty. If the value is :graphics, but there is no X display, then we quietly use the TTY interface.

2.9.2 The TTY Inspector

If X is unavailable, a terminal inspector is invoked. The TTY inspector is a crude interface to describe which allows objects to be traversed and maintains a history. This inspector prints information about and object and a numbered list of the components of the object. The command-line based interface is a normal read–eval–print loop, but an integer n descends into the n’th component of the current object, and symbols with these special names are interpreted as commands:

U

Move back to the enclosing object. As you descend into the components of an object, a stack of all the objects previously seen is kept. This command pops you up one level of this stack.

Q, E

Return the current object from inspect.

R

Recompute object display, and print again. Useful if the object may have changed.

D

Display again without recomputing.

H, ?

Show help message.

2.11.1 Reader Extensions

CMUCL supports an ANSI-compatible extension to enable reading of specialized arrays. Thus

  * (setf *print-readably* nil)
  NIL
  * (make-array '(2 2) :element-type '(signed-byte 8))
  #2A((0 0) (0 0))
  * (setf *print-readably* t)
  T
  * (make-array '(2 2) :element-type '(signed-byte 8))
  #A((SIGNED-BYTE 8) (2 2) ((0 0) (0 0)))
  * (type-of (read-from-string "#A((SIGNED-BYTE 8) (2 2) ((0 0) (0 0)))"))
  (SIMPLE-ARRAY (SIGNED-BYTE 8) (2 2))
  * (setf *print-readably* nil)
  NIL
  * (type-of (read-from-string "#A((SIGNED-BYTE 8) (2 2) ((0 0) (0 0)))"))
  (SIMPLE-ARRAY (SIGNED-BYTE 8) (2 2))

2.11.2 Reader Parameters

Variable: extensions:*ignore-extra-close-parentheses* ¶

If this variable is t (the default), then the reader merely prints a warning when an extra close parenthesis is detected (instead of signalling an error.)

2.14.1 Process Accessors

The following functions interface the process returned by run-program:

Function: extensions:process-p thing ¶

This function returns t if thing is a process. Otherwise it returns nil

Function: extensions:process-pid process ¶

This function returns the process ID, an integer, for the process.

Function: extensions:process-status process ¶

This function returns the current status of process, which is one of :running, :stopped, :exited, or :signaled.

Function: extensions:process-exit-code process ¶

This function returns either the exit code for process, if it is :exited, or the termination signal process if it is :signaled. The result is undefined for processes that are still alive.

Function: extensions:process-core-dumped process ¶

This function returns t if someone used a Unix signal to terminate the process and caused it to dump a Unix core image.

Function: extensions:process-pty process ¶

This function returns either the two-way stream connected to process’s Unix PTY connection or nil if there is none.

Function: extensions:process-input process ¶

Function: extensions:process-output process ¶

Function: extensions:process-error process ¶

If the corresponding stream was created, these functions return the input, output or error fd-stream. nil is returned if there is no stream.

Function: extensions:process-status-hook process ¶

This function returns the current function to call whenever process’s status changes. This function takes the process as a required argument. process-status-hook is setf’able.

Function: extensions:process-plist process ¶

This function returns annotations supplied by users, and it is setf’able. This is available solely for users to associate information with process without having to build a-lists or hash tables of process structures.

Function: extensions:process-wait process &optional check-for-stopped ¶

This function waits for process to finish. If check-for-stopped is non-nil, this also returns when process stops.

Function: extensions:process-kill process signal &optional whom ¶

This function sends the Unix signal to process. Signal should be the number of the signal or a keyword with the Unix name (for example, :sigsegv). Whom should be one of the following:

:pid

This is the default, and it indicates sending the signal to process only.

:process-group

This indicates sending the signal to process’s group.

:pty-process-group

This indicates sending the signal to the process group currently in the foreground on the Unix PTY connected to process. This last option is useful if the running program is a shell, and you wish to signal the program running under the shell, not the shell itself. If process-pty of process is nil, using this option is an error.

Function: extensions:process-alive-p process ¶

This function returns t if process’s status is either :running or :stopped.

Function: extensions:process-close process ¶

This function closes all the streams associated with process. When you are done using a process, call this to reclaim system resources.

2.16.1 Unix Pathnames

Unix pathnames are always parsed with a unix-host object as the host and nil as the device. The last two dots (.) in the namestring mark the type and version, however if the first character is a dot, it is considered part of the name. If the last character is a dot, then the pathname has the empty-string as its type. The type defaults to nil and the version defaults to :newest.

(defun parse (x)
  (values (pathname-name x) (pathname-type x) (pathname-version x)))

(parse "foo") ⇒ "foo", NIL, NIL
(parse "foo.bar") ⇒ "foo", "bar", NIL
(parse ".foo") ⇒ ".foo", NIL, NIL
(parse ".foo.bar") ⇒ ".foo", "bar", NIL
(parse "..") ⇒ NIL, NIL, NIL
(parse "foo.") ⇒ "foo", "", NIL
(parse "foo.bar.~1~") ⇒ "foo", "bar", 1
(parse "foo.bar.baz") ⇒ "foo.bar", "baz", NIL

The directory of pathnames beginning with a slash (or a search-list, see search-lists) is starts :absolute, others start with :relative. The .. directory is parsed as :up; there is no namestring for :back:

(pathname-directory "/usr/foo/bar.baz") ⇒ (:ABSOLUTE "usr" "foo")
(pathname-directory "../foo/bar.baz") ⇒ (:RELATIVE :UP "foo")

2.16.2 Wildcard Pathnames

Wildcards are supported in Unix pathnames. If ‘*’ is specified for a part of a pathname, that is parsed as :wild. ‘**’ can be used as a directory name to indicate :wild-inferiors. Filesystem operations treat :wild-inferiors the same as :wild, but pathname pattern matching (e.g. for logical pathname translation, see logical-pathnames) matches any number of directory parts with ‘**’ (see see wildcard-matching.)

‘*’ embedded in a pathname part matches any number of characters. Similarly, ‘?’ matches exactly one character, and ‘[a,b]’ matches the characters ‘a’ or ‘b’. These pathname parts are parsed as pattern objects.

Backslash can be used as an escape character in namestring parsing to prevent the next character from being treated as a wildcard. Note that if typed in a string constant, the backslash must be doubled, since the string reader also uses backslash as a quote:

(pathname-name "foo\\*bar") => "foo*bar"

2.16.3 Logical Pathnames

If a namestring begins with the name of a defined logical pathname host followed by a colon, then it will be parsed as a logical pathname. Both ‘*’ and ‘**’ wildcards are implemented. load-logical-pathname-translations on name looks for a logical host definition file in library:name.translations. Note that library: designates the search list (see search-lists) initialized to the CMUCL lib/ directory, not a logical pathname. The format of the file is a single list of two-lists of the from and to patterns:

(("foo;*.text" "/usr/ram/foo/*.txt")
 ("foo;*.lisp" "/usr/ram/foo/*.l"))

2.16.4 Search Lists

Search lists are an extension to Common Lisp pathnames. They serve a function somewhat similar to Common Lisp logical pathnames, but work more like Unix PATH variables. Search lists are used for two purposes:

• They provide a convenient shorthand for commonly used directory names, and
• They allow the abstract (directory structure independent) specification of file locations in program pathname constants (similar to logical pathnames.)

Each search list has an associated list of directories (represented as pathnames with no name or type component.) The namestring for any relative pathname may be prefixed with “slist:”, indicating that the pathname is relative to the search list slist (instead of to the current working directory.) Once qualified with a search list, the pathname is no longer considered to be relative.

When a search list qualified pathname is passed to a file-system operation such as open, load or truename, each directory in the search list is successively used as the root of the pathname until the file is located. When a file is written to a search list directory, the file is always written to the first directory in the list.

2.16.5 Predefined Search-Lists

These search-lists are initialized from the Unix environment or when Lisp was built:

default:

The current directory at startup.

home:

The user’s home directory.

library:

The CMUCL lib/ directory (CMUCLLIB environment variable).

path:

The Unix command path (PATH environment variable).

ld-library-path:

The Unix LD_LIBRARY_PATH environment variable.

target:

The root of the tree where CMUCL was compiled.

modules:

The list of directories where CMUCL’s modules can be found.

ext-formats:

The list of directories where CMUCL can find the implementation of external formats.

It can be useful to redefine these search-lists, for example, library: can be augmented to allow logical pathname translations to be located, and target: can be redefined to point to where CMUCL system sources are locally installed.

2.16.6 Search-List Operations

These operations define and access search-list definitions. A search-list name may be parsed into a pathname before the search-list is actually defined, but the search-list must be defined before it can actually be used in a filesystem operation.

Function: extensions:search-list name ¶

This function returns the list of directories associated with the search list name. If name is not a defined search list, then an error is signaled. When set with setf, the list of directories is changed to the new value. If the new value is just a namestring or pathname, then it is interpreted as a one-element list. Note that (unlike Unix pathnames), search list names are case-insensitive.

Function: extensions:search-list-defined-p name ¶

Function: extensions:clear-search-list name ¶

search-list-defined-p returns t if name is a defined search list name, nil otherwise. clear-search-list make the search list name undefined.

Macro: extensions:enumerate-search-list (var pathname {result}) {form}* ¶

This macro provides an interface to search list resolution. The body forms are executed with var bound to each successive possible expansion for name. If name does not contain a search-list, then the body is executed exactly once. Everything is wrapped in a block named nil, so return can be used to terminate early. The result form (default nil) is evaluated to determine the result of the iteration.

2.16.7 Search List Example

The search list code: can be defined as follows:

(setf (ext:search-list "code:") '("/usr/lisp/code/"))

It is now possible to use code: as an abbreviation for the directory /usr/lisp/code/ in all file operations. For example, you can now specify code:eval.lisp to refer to the file /usr/lisp/code/eval.lisp.

To obtain the value of a search-list name, use the function search-list as follows:

(ext:search-list name)

Where name is the name of a search list as described above. For example, calling ext:search-list on code: as follows:

(ext:search-list "code:")

returns the list ("/usr/lisp/code/").

2.17.1 Wildcard Matching

Unix filesystem operations such as open will accept wildcard pathnames that match a single file (of course, directory allows any number of matches.) Filesystem operations treat :wild-inferiors the same as :wild.

Function: directory wildname &key :all :check-for-subdirs ¶

:truenamep :follow-links

The keyword arguments to this Common Lisp function are a CMUCL extension. The arguments (all default to t) have the following functions:

:all

Include files beginning with dot such as .login, similar to “ls -a”.

:check-for-subdirs

Test whether files are directories, similar to “ls -F”.

:truenamep

Call truename on each file, which expands out all symbolic links. Note that this option can easily result in pathnames being returned which have a different directory from the one in the wildname argument.

:follow-links

Follow symbolic links when searching for matching directories.

Function: extensions:print-directory wildname &optional stream &key :all :verbose :return-list ¶

Print a directory of wildname listing to stream (default *standard-output*.) :all and :verbose both default to nil and correspond to the “-a” and “-l” options of ls. Normally this function returns nil, but if :return-list is true, a list of the matched pathnames are returned.

2.17.2 File Name Completion

Function: extensions:complete-file pathname &key :defaults :ignore-types ¶

Attempt to complete a file name to the longest unambiguous prefix. If supplied, directory from :defaults is used as the “working directory” when doing completion. :ignore-types is a list of strings of the pathname types (a.k.a. extensions) that should be disregarded as possible matches (binary file names, etc.)

Function: extensions:ambiguous-files pathname &optional defaults ¶

Return a list of pathnames for all the possible completions of pathname with respect to defaults.

2.17.3 Miscellaneous Filesystem Operations

Function: extensions:default-directory ¶

Return the current working directory as a pathname. If set with setf, set the working directory.

Function: extensions:file-writable name ¶

This function accepts a pathname and returns t if the current process can write it, and nil otherwise.

Function: extensions:unix-namestring pathname &optional for-input ¶

This function converts pathname into a string that can be used with UNIX system calls. Search-lists and wildcards are expanded. for-input controls the treatment of search-lists: when true (the default) and the file exists anywhere on the search-list, then that absolute pathname is returned; otherwise the first element of the search-list is used as the directory.

2.19.1 MT-19937 Generator

Note: This generator is deprecated in favor of the xoroshiro128+ generator (see xoroshiro128+ Generator) which is faster and uses less memory.

On all platforms, the random number is MT-19937 generator as indicated by :rand-mt19937 being in *features*. This is a Lisp implementation of the MT-19937 generator of Makoto Matsumoto and T. Nishimura. We refer the reader to their paper² or to their website.

When CMUCL starts up, *random-state* is initialized by reading 627 words from /dev/urandom, when available. If /dev/urandom is not available, the universal time is used to initialize *random-state*. The initialization is done as given in Matsumoto’s paper.

2.19.2 xoroshiro128+ Generator

On supported platforms, the random number generator is xoroshiro128+ generator, as indicated by :random-xoroshiro being in *features*. This is a Lisp implementation of the xoroshiro128+ generator by David Blackman and Sebastiano Vigna. See http://xoroshiro.di.unimi.it for further details.

This generator replaces the MT-19937 generator (see MT-19937 Generator) because it is faster and uses much less memory for the generator (4 32-bit words). However, the period is shorter.

When CMUCL starts up, *random-state* is initialized by reading 4 32-bit words from /dev/urandom, when available. If /dev/urandom is not available, the universal time is used to initialize *random-state*. The initialization is done is using splitmix64 with get-universal-time.

Function: kernel:random-state-jump &optional (rng-state *random-state*) ¶

Jump the rng-state. This is equivalent to 2^{64} calls to the xoroshiro128+ generator. It can be used to generate 2^{64} non-overlapping subsequences for parallel computations.

2.23.1 Primary Method Errors

The standard requires that an error is signaled when a generic function is called and

• no primary method is applicable to the generic function’s actual arguments, and
• the generic function’s method combination is either the standard method combination or a method combination defined with the short form of define-method-combination. The latter includes the standardized method combinations like progn, and, etc.

Generic Function: pcl:no-primary-method gf &rest args ¶

In CMUCL, this generic function is called in the above erroneous cases. The parameter gf is the generic function being called, and args is a list of actual arguments in the generic function call.

Method: pcl:no-primary-method gf standard-generic-function) &rest args ¶

This method signals a continuable error of type pcl:no-primary-method-error.

2.23.2 Slot Type Checking

Declared slot types are used when

• reading slot values with slot-value in methods, or
• setting slots with (setf slot-value) in methods, or
• creating instances with make-instance, when slots are initialized from initforms. This currently depends on PCL being able to use its internal make-instance optimization, which it usually can.

Example:

(defclass foo ()
  ((a :type fixnum)))

(defmethod bar ((object foo) value)
  (with-slots (a) object
    (setf a value)))

(defmethod baz ((object foo))
  (< (slot-value object 'a) 10))

In method bar, and with a suitable safety setting, a type error will occur if value is not a fixnum. In method baz, a fixnum comparison can be used by the compiler.

Variable: pcl::*use-slot-types-p* ¶

Slot type checking can be turned off by setting this variable to nil, which can be useful for compiling code containing incorrect slot type declarations.

2.23.3 Slot Access Optimization

The declaration ext:slots is used for optimizing slot access in methods.

declare (ext:slots specifier*)

specifier   ::= (quality class-entry*)
quality     ::= SLOT-BOUNDP | INLINE
class-entry ::= class | (class slot-name*)
class       ::= the name of a class
slot-name   ::= the name of a slot

The slot-boundp quality specifies that all or some slots of a class are always bound.

The inline quality specifies that access to all or some slots of a class should be inlined, using compile-time knowledge of class layouts.

• slot-boundp Declaration
• inline Declaration
• Automatic Method Recompilation

(defclass foo ()
  (a b))

(defmethod bar ((x foo))
  (declare (ext:slots (slot-boundp foo)))
  (list (slot-value x 'a) (slot-value x 'b)))

(defclass foo ()
  (a b))

(defmethod bar ((x foo))
  (declare (ext:slots (inline (foo a))))
  (list (slot-value x 'a) (slot-value x 'b)))

(declaim (ext:slots (inline (foo slot-a))))
(defclass foo () ...)
(defclass bar (foo) ...)

declaim (ext:auto-compile specifier*)
declaim (ext:not-auto-compile specifier*)

specifier   ::= gf-name | (gf-name qualifier* (specializer*))
gf-name     ::= the name of a generic function
qualifier   ::= a method qualifier
specializer ::= a method specializer

(declaim (ext:auto-compile foo))
(defmethod foo :around ((x bar)) ...)

(declaim (ext:auto-compile (foo (bar))))
(defmethod foo :around ((x bar)) ...)
(defmethod foo ((x bar)) ...)

(declaim (ext:auto-compile foo))
(declaim (ext:not-auto-compile (foo :around (bar)))  
(defmethod foo :around ((x bar)) ...)
(defmethod foo ((x bar)) ...)

2.23.4 Inlining Methods in Effective Methods

When a generic function is called, an effective method is constructed from applicable methods. The effective method is called with the original arguments, and itself calls applicable methods according to the generic function’s method combination. Some of the function call overhead in effective methods can be removed by inlining methods in effective methods, at the expense of increased code size.

Inlining of methods is controlled by the usual inline declaration. In the following example, both foo methods shown will be inlined in effective methods:

(declaim (inline (method foo (foo))
                 (method foo :before (foo))))
(defmethod foo ((x foo)) ...)
(defmethod foo :before ((x foo)) ...)

Please note that this form of inlining has no noticeable effect for effective methods that consist of a primary method only, which doesn’t have keyword arguments. In such cases, PCL uses the primary method directly for the effective method.

When the definition of an inlined method is changed, effective methods are not automatically updated to reflect the change. This is just as it is when inlining normal functions. Different from the normal case is that users do not have direct access to effective methods, as it would be the case when a function is inlined somewhere else. Because of this, the function pcl:flush-emf-cache is provided for forcing such an update of effective methods.

Function: pcl:flush-emf-cache &optional gf ¶

Flush cached effective method functions. If gf is supplied, it should be a generic function metaobject or the name of a generic function, and this function flushes all cached effective methods for the given generic function. If gf is not supplied, all cached effective methods are flushed.

Variable: pcl::*inline-methods-in-emfs* ¶

If true, the default, perform method inlining as described above. If false, don’t.

2.23.5 Effective Method Precomputation

When a generic function is called, the generic function’s discriminating function computes the set of methods applicable to actual arguments and constructs an effective method function from applicable methods, using the generic function’s method combination.

Effective methods can be precomputed at method load time instead of when the generic function is called depending on the value of pcl:*max-emf-precomputation-methods*.

Variable: pcl:*max-emf-precomputation-methods* ¶

If nonzero, the default value is 100, precompute effective methods when methods are loaded, and the method’s generic function has less than the specified number of methods.

If zero, compute effective methods only when the generic function is called.

2.23.6 Sealing

Support for sealing classes and generic functions have been implemented. Please note that this interface is subject to change.

Macro: pcl:seal name (var) &rest specifiers ¶

Seal name with respect to the given specifiers; name can be the name of a class or generic-function.

Supported specifiers are :subclasses for classes, which prevents changing subclasses of a class, and :methods which prevents changing the methods of a generic function.

Sealing violations signal an error of type pcl:sealed-error.

Function: pcl:unseal name-or-object ¶

Remove seals from name-or-object.

2.23.7 Method Tracing and Profiling

Methods can be traced with trace, using function names of the form (method <name> <qualifiers> <specializers>). Example:

(defmethod foo ((x integer)) x)
(defmethod foo :before ((x integer)) x)

(trace (method foo (integer)))
(trace (method foo :before (integer)))
(untrace (method foo :before (integer)))

trace and untrace also allow a name specifier :methods gf-form for tracing all methods of a generic function:

(trace :methods 'foo)
(untrace :methods 'foo)

Methods can also be specified for the :wherein option to trace. Because this option is a name or a list of names, methods must be specified as a list. Thus, to trace all calls of foo from the method bar specialized on integer argument, use

  (trace foo :wherein ((method bar (integer))))

Before and after methods are supported as well:

  (trace foo :wherein ((method bar :before (integer))))

Method profiling is done analogously to trace:

(defmethod foo ((x integer)) x)
(defmethod foo :before ((x integer)) x)

(profile:profile (method foo (integer)))
(profile:profile (method foo :before (integer)))
(profile:unprofile (method foo :before (integer)))

(profile:profile :methods 'foo)
(profile:unprofile :methods 'foo)

(profile:profile-all :methods t)

2.23.8 Misc

Variable: pcl::*compile-interpreted-methods-p* ¶

This variable controls compilation of interpreted method functions, e.g. for methods defined interactively at the REPL. Default is true, that is, method functions are compiled.

2.24.1 Extensions

Function: constantly value &optional val1 val2 &rest more-values ¶

As an extension, CMUCL allows constantly to accept more than one value which are returned as multiple values.

2.26.1 &rest argument lists

Rest argument lists can be allocated on the stack by declaring the rest argument variable dynamic-extent. Examples:

(defun foo (x &rest rest)
  (declare (dynamic-extent rest))
  ...)

(defun bar ()
  (lambda (&rest rest)
    (declare (dynamic-extent rest))
    ...))

2.26.2 Closures

Closures for local functions can be allocated on the stack if the local function is declared dynamic-extent, and the closure appears as an argument in the call of a named function. In the example:

(defun foo (x)
  (flet ((bar () x))
    (declare (dynamic-extent #'bar))
    (baz #'bar)))

the closure passed to function baz is allocated on the stack. Likewise in the example:

(defun foo (x)
  (flet ((bar () x))
    (baz #'bar)
    (locally (declare (dynamic-extent #'bar))
      (baz #'bar))))

Stack-allocation of closures can also automatically take place when calling certain known CL functions taking function arguments, for example some or find-if.

2.26.3 list, list*, and cons

New conses allocated by list, list*, or cons which are used to initialize variables can be allocated from the stack if the variables are declared dynamic-extent. In the case of cons, only the outermost cons cell is allocated from the stack; this is an arbitrary restriction.

(let ((x (list 1 2))
      (y (list* 1 2 x))
      (z (cons 1 (cons 2 nil))))
  (declare (dynamic-extent x y z))
  ...
  (setq x (list 2 3))
  ...)

Please note that the setq of x in the example program assigns to x a list that is allocated from the heap. This is another arbitrary restriction that exists because other Lisps behave that way.

2.29.1 Dictionary

Function: intl:translation-enable ¶

Enable recording of translatable strings.

Function: intl:translation-disable ¶

Disablle recording of translatable strings.

Function: intl:setlocale &optional locale ¶

Sets the locale to the locale specified by locale. If locale is not give or is nil, the locale is determined by look at the environment variables LANGUAGE, LC_ALL, LC_MESSAGES, or LANG. If none of these are set, the locale is unchanged.

The default locale is “C”.

Function: intl:textdomain domain ¶

Set the default domain to the domain specified by domain. Typically, this only needs to be done at the top of each source file. This is used to gettext and ngettext to set the domain for the message string.

Macro: intl:gettext string ¶

Look up the specified string, string, in the current message domain and return its translation.

Function: intl:dgettext domain string ¶

Look up the specified string, string, in the message domain, domain. The translation is returned.

When compiled, this also function also records the string so that an appropriate message template file can be created. (See intl::dump-pot-files.)

Macro: intl:ngettext singular plural n ¶

Look up the singular or plural form of a message in the default domain. The singular form is singular; the plural is plural. The number of items is specified by n in case the correct translation depends on the actual number of items.

Function: intl:dngettext domain singular plural n ¶

Look up the singular or plural form of a message in the specified domain, domain. The singular form is singular; the plural is plural. The number of items is specified by n in case the correct translation depends on the actual number of items.

When compiled, this also function also records the singular and plural forms so that an appropriate message template file can be created. (See intl::dump-pot-files.)

Function: intl::dump-pot-files &key :copyright :output-directory ¶

Dumps the translatable strings recorded by dgettext and dngettext. The message template file (pot file) is written to a file in the directory specified by output-directory, and the name of the file is the domain of the string.

If copyright is specified, this is placed in the output file as the copyright message.

Variable: intl:*locale-directories* ¶

This is a list of directory pathnames where the translations can be found.

Function: intl:install &optional (rt *readtable*) ¶

Installs reader macros and comment reader into the specified readtable as explained below. The readtable defaults to *readtable*.

Two reader macros are also provided: _'' and _N''. The first is equivalent to wrapping dgettext around the string. The second returns the string, but also records the string. This is needed when we want to record a docstring for translation or any other string in a place where a macro or function call would be incorrect.

Also, the standard comment reader is extended to allow translator comments to be saved and written to the messages template file so that the translator may not need to look at the original source to understand the string. Any comment line that begins with exactly "TRANSLATORS: " is saved. This means each translator comment must be preceded by this string to be saved; the translator comment ends at the end of each line.

2.29.2 Example Usage

Here is a simple example of how to localize your code. Let the file intl-ex.lisp contain:

(intl:textdomain "example")  

(defun foo (x y)
  "Cool function foo of x and y"
  (let ((result (bar x y)))
    ;; TRANSLATORS:  One line comment about bar.
    (format t _"bar of ~A and ~A = ~A~%" x y result)
    #| TRANSLATORS:  Multiline comment about
    how many Xs there are
    |#
    (format t (intl:ngettext "There is one X"
                             "There are many Xs"
                             x))
    result))

The call to textdomain sets the default domain for all translatable strings following the call.

Here is a sample session for creating a template file:

* (intl:install)

T
* (intl:translation-enable)

T
* (compile-file "intl-ex")

#P"/Volumes/share/cmucl/cvs/intl-ex.sse2f"
NIL
NIL
* (intl::dump-pot-files :output-directory "./")

Dumping 3 messages for domain "example"
NIL
*

When this file is compiled, all of the translatable strings are recorded. This includes the docstring for foo, the string for the first format, and the string marked by the call to intl:ngettext.

A file named “example.pot” in the directory “./” is created. The contents of this file are:

# example

# SOME DESCRIPTIVE TITLE
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION"
"Report-Msgid-Bugs-To: "
"PO-Revision-Date: YEAR-MO-DA HO:MI +ZONE"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>"
"Language-Team: LANGUAGE <LL@li.org>"
"MIME-Version: 1.0"
"Content-Type: text/plain; charset=UTF-8"
"Content-Transfer-Encoding: 8bit"

#.  One line comment about bar.
#: intl-ex.lisp
msgid "bar of ~A and ~A = ~A~%"
msgstr ""

#.  Multiline comment about
    how many Xs there are
#: intl-ex.lisp
msgid "Cool function foo of x and y"
msgstr ""

#: intl-ex.lisp
msgid "There is one X"
msgid_plural "There are many Xs"
msgstr[0] ""

To finish the translation, a corresponding “example.po” file needs to be created with the appropriate translations for the given strings. This file must be placed in some directory that is included in intl:*locale-directories*.

Suppose the translation is done for Korean. Then the user can set the environment variables appropriately or call (intl:setlocale "ko"). Note that the external format for the standard streams needs to be set up appropriately too. It is up to the user to set this correctly. Once this is all done, the output from the function foo will now be in Korean instead of English as in the original source file.

For further information, we refer the reader to documentation on

gettext.

3.3.1 Stack Motion

These commands move to a new stack frame and print the name of the function and the values of its arguments in the style of a Lisp function call:

up

Move up to the next higher frame. More recent function calls are considered to be higher on the stack.

down

Move down to the next lower frame.

top

Move to the highest frame.

bottom

Move to the lowest frame.

frame [n]

Move to the frame with the specified number. Prompts for the number if not supplied.

3.3.2 How Arguments are Printed

A frame is printed to look like a function call, but with the actual argument values in the argument positions. So the frame for this call in the source:

(myfun (+ 3 4) 'a)

would look like this:

(MYFUN 7 A)

All keyword and optional arguments are displayed with their actual values; if the corresponding argument was not supplied, the value will be the default. So this call:

(subseq "foo" 1)

would look like this:

(SUBSEQ "foo" 1 3)

And this call:

(string-upcase "test case")

would look like this:

(STRING-UPCASE "test case" :START 0 :END NIL)

The arguments to a function call are displayed by accessing the argument variables. Although those variables are initialized to the actual argument values, they can be set inside the function; in this case the new value will be displayed.

&rest arguments are handled somewhat differently. The value of the rest argument variable is displayed as the spread-out arguments to the call, so:

(format t "~A is a ~A." "This" 'test)

would look like this:

(FORMAT T "~A is a ~A." "This" 'TEST)

Rest arguments cause an exception to the normal display of keyword arguments in functions that have both &rest and &key arguments. In this case, the keyword argument variables are not displayed at all; the rest arg is displayed instead. So for these functions, only the keywords actually supplied will be shown, and the values displayed will be the argument values, not values of the (possibly modified) variables.

If the variable for an argument is never referenced by the function, it will be deleted. The variable value is then unavailable, so the debugger prints #<unused-arg> instead of the value. Similarly, if for any of a number of reasons (described in more detail in section debug-vars) the value of the variable is unavailable or not known to be available, then #<unavailable-arg> will be printed instead of the argument value.

Printing of argument values is controlled by *debug-print-level* and debug-print-length.

3.3.3 Function Names

If a function is defined by defun, labels, or flet, then the debugger will print the actual function name after the open parenthesis, like:

(STRING-UPCASE "test case" :START 0 :END NIL)
((SETF AREF) #\a "for" 1)

Otherwise, the function name is a string, and will be printed in quotes:

("DEFUN MYFUN" BAR)
("DEFMACRO DO" (DO ((I 0 (1+ I))) ((= I 13))) NIL)
("SETQ *GC-NOTIFY-BEFORE*")

This string name is derived from the defmumble form that encloses or expanded into the lambda, or the outermost enclosing form if there is no defmumble.

3.3.4 Funny Frames

Sometimes the evaluator introduces new functions that are used to implement a user function, but are not directly specified in the source. The main place this is done is for checking argument type and syntax. Usually these functions do their thing and then go away, and thus are not seen on the stack in the debugger. But when you get some sort of error during lambda-list processing, you end up in the debugger on one of these funny frames.

These funny frames are flagged by printing “[keyword]” after the parentheses. For example, this call:

(car 'a 'b)

will look like this:

(CAR 2 A) [:EXTERNAL]

And this call:

(string-upcase "test case" :end)

would look like this:

("DEFUN STRING-UPCASE" "test case" 335544424 1) [:OPTIONAL]

As you can see, these frames have only a vague resemblance to the original call. Fortunately, the error message displayed when you enter the debugger will usually tell you what problem is (in these cases, too many arguments and odd keyword arguments.) Also, if you go down the stack to the frame for the calling function, you can display the original source (see source-locations.)

With recursive or block compiled functions (see block-compilation), an :EXTERNAL frame may appear before the frame representing the first call to the recursive function or entry to the compiled block. This is a consequence of the way the compiler does block compilation: there is nothing odd with your program. You will also see :CLEANUP frames during the execution of unwind-protect cleanup code. Note that inline expansion and open-coding affect what frames are present in the debugger, see sections debugger-policy and open-coding.

3.3.5 Debug Tail Recursion

Both the compiler and the interpreter are “properly tail recursive.” If a function call is in a tail-recursive position, the stack frame will be deallocated at the time of the call, rather than after the call returns. Consider this backtrace:

(BAR ...) 
(FOO ...)

Because of tail recursion, it is not necessarily the case that FOO directly called BAR. It may be that FOO called some other function FOO2 which then called BAR tail-recursively, as in this example:

(defun foo ()
  ...
  (foo2 ...)
  ...)

(defun foo2 (...)
  ...
  (bar ...))

(defun bar (...)
  ...)

Usually the elimination of tail-recursive frames makes debugging more pleasant, since theses frames are mostly uninformative. If there is any doubt about how one function called another, it can usually be eliminated by finding the source location in the calling frame (section source-locations.)

The elimination of tail-recursive frames can be prevented by disabling tail-recursion optimization, which happens when the debug optimization quality is greater than 2 (see debugger-policy.)

For a more thorough discussion of tail recursion, see tail-recursion.

3.3.6 Unknown Locations and Interrupts

The debugger operates using special debugging information attached to the compiled code. This debug information tells the debugger what it needs to know about the locations in the code where the debugger can be invoked. If the debugger somehow encounters a location not described in the debug information, then it is said to be unknown. If the code location for a frame is unknown, then some variables may be inaccessible, and the source location cannot be precisely displayed.

There are three reasons why a code location could be unknown:

• There is inadequate debug information due to the value of the debug optimization quality. See debugger-policy.
• The debugger was entered because of an interrupt such as ^C.
• A hardware error such as “bus error” occurred in code that was compiled unsafely due to the value of the safety optimization quality. See optimize-declaration.

In the last two cases, the values of argument variables are accessible, but may be incorrect. See debug-var-validity for more details on when variable values are accessible.

It is possible for an interrupt to happen when a function call or return is in progress. The debugger may then flame out with some obscure error or insist that the bottom of the stack has been reached, when the real problem is that the current stack frame can’t be located. If this happens, return from the interrupt and try again.

When running interpreted code, all locations should be known. However, an interrupt might catch some subfunction of the interpreter at an unknown location. In this case, you should be able to go up the stack a frame or two and reach an interpreted frame which can be debugged.

3.4.1 Variable Value Availability

The value of a variable may be unavailable to the debugger in portions of the program where Common Lisp says that the variable is defined. If a variable value is not available, the debugger will not let you read or write that variable. With one exception, the debugger will never display an incorrect value for a variable. Rather than displaying incorrect values, the debugger tells you the value is unavailable.

The one exception is this: if you interrupt (e.g., with ^C) or if there is an unexpected hardware error such as “bus error” (which should only happen in unsafe code), then the values displayed for arguments to the interrupted frame might be incorrect.⁴ This exception applies only to the interrupted frame: any frame farther down the stack will be fine.

The value of a variable may be unavailable for these reasons:

• The value of the debug optimization quality may have omitted debug information needed to determine whether the variable is available. Unless a variable is an argument, its value will only be available when debug is at least 2.
• The compiler did lifetime analysis and determined that the value was no longer needed, even though its scope had not been exited. Lifetime analysis is inhibited when the debug optimization quality is 3.
• The variable’s name is an uninterned symbol (gensym). To save space, the compiler only dumps debug information about uninterned variables when the debug optimization quality is 3.
• The frame’s location is unknown (see unknown-locations) because the debugger was entered due to an interrupt or unexpected hardware error. Under these conditions the values of arguments will be available, but might be incorrect. This is the exception above.
• The variable was optimized out of existence. Variables with no reads are always optimized away, even in the interpreter. The degree to which the compiler deletes variables will depend on the value of the compile-speed optimization quality, but most source-level optimizations are done under all compilation policies.

Since it is especially useful to be able to get the arguments to a function, argument variables are treated specially when the speed optimization quality is less than 3 and the debug quality is at least 1. With this compilation policy, the values of argument variables are almost always available everywhere in the function, even at unknown locations. For non-argument variables, debug must be at least 2 for values to be available, and even then, values are only available at known locations.

3.4.2 Note On Lexical Variable Access

When the debugger command loop establishes variable bindings for available variables, these variable bindings have lexical scope and dynamic extent.⁵ You can close over them, but such closures can’t be used as upward funargs.

You can also set local variables using setq, but if the variable was closed over in the original source and never set, then setting the variable in the debugger may not change the value in all the functions the variable is defined in. Another risk of setting variables is that you may assign a value of a type that the compiler proved the variable could never take on. This may result in bad things happening.

3.5.1 How the Source is Found

If the code was defined from Common Lisp by compile or eval, then the source can always be reliably located. If the code was defined from a fasl file created by compile-file, then the debugger gets the source forms it prints by reading them from the original source file. This is a potential problem, since the source file might have moved or changed since the time it was compiled.

The source file is opened using the truename of the source file pathname originally given to the compiler. This is an absolute pathname with all logical names and symbolic links expanded. If the file can’t be located using this name, then the debugger gives up and signals an error.

If the source file can be found, but has been modified since the time it was compiled, the debugger prints this warning:

; File has been modified since compilation:
;   filename
; Using form offset instead of character position.

where filename is the name of the source file. It then proceeds using a robust but not foolproof heuristic for locating the source. This heuristic works if:

• No top-level forms before the top-level form containing the source have been added or deleted, and
• The top-level form containing the source has not been modified much. (More precisely, none of the list forms beginning before the source form have been added or deleted.)

If the heuristic doesn’t work, the displayed source will be wrong, but will probably be near the actual source. If the “shape” of the top-level form in the source file is too different from the original form, then an error will be signaled. When the heuristic is used, the the source location commands are noticeably slowed.

Source location printing can also be confused if (after the source was compiled) a read-macro you used in the code was redefined to expand into something different, or if a read-macro ever returns the same eq list twice. If you don’t define read macros and don’t use ## in perverted ways, you don’t need to worry about this.

3.5.2 Source Location Availability

Source location information is only available when the debug optimization quality is at least 2. If source location information is unavailable, the source commands will give an error message.

If source location information is available, but the source location is unknown because of an interrupt or unexpected hardware error (see unknown-locations), then the command will print:

Unknown location: using block start.

and then proceed to print the source location for the start of the basic block enclosing the code location. It’s a bit complicated to explain exactly what a basic block is, but here are some properties of the block start location:

• The block start location may be the same as the true location.
• The block start location will never be later in the the program’s flow of control than the true location.
• No conditional control structures (such as if, cond, or) will intervene between the block start and the true location (but note that some conditionals present in the original source could be optimized away.) Function calls do not end basic blocks.
• The head of a loop will be the start of a block.
• The programming language concept of “block structure” and the Common Lisp block special form are totally unrelated to the compiler’s basic block.

In other words, the true location lies between the printed location and the next conditional (but watch out because the compiler may have changed the program on you.)

3.9.1 Breakpoint Example

Consider this definition of the factorial function:

(defun ! (n)
  (if (zerop n)
      1
      (* n (! (1- n)))))

This debugger session demonstrates the use of breakpoints:

common-lisp-user> (break) ; Invoke debugger

Break

Restarts:
  0: [CONTINUE] Return from BREAK.
  1: [ABORT   ] Return to Top-Level.

Debug  (type H for help)

(INTERACTIVE-EVAL (BREAK))
0] ll #'!
0: #'(LAMBDA (N) (BLOCK ! (IF # 1 #)))
1: (ZEROP N)
2: (* N (! (1- N)))
3: (1- N)
4: (! (1- N))
5: (* N (! (1- N)))
6: #'(LAMBDA (N) (BLOCK ! (IF # 1 #)))
0] br 2
(* N (! (1- N)))
1: 2 in !
Added.
0] q

common-lisp-user> (! 10) ; Call the function

*Breakpoint hit*

Restarts:
  0: [CONTINUE] Return from BREAK.
  1: [ABORT   ] Return to Top-Level.

Debug  (type H for help)

(! 10) ; We are now in first call (arg 10) before the multiply
Source: (* N (! (1- N)))
3] st

*Step*

(! 10) ; We have finished evaluation of (1- n)
Source: (1- N)
3] st

*Breakpoint hit*

Restarts:
  0: [CONTINUE] Return from BREAK.
  1: [ABORT   ] Return to Top-Level.

Debug  (type H for help)

(! 9) ; We hit the breakpoint in the recursive call
Source: (* N (! (1- N)))
3] 

3.10.1 Encapsulation Functions

The encapsulation functions provide a mechanism for intercepting the arguments and results of a function. ext:encapsulate changes the function definition of a symbol, and saves it so that it can be restored later. The new definition normally calls the original definition. The Common Lisp fdefinition function always returns the original definition, stripping off any encapsulation.

The original definition of the symbol can be restored at any time by the ext:unencapsulate function. ext:encapsulate and ext:unencapsulate allow a symbol to be multiply encapsulated in such a way that different encapsulations can be completely transparent to each other.

Each encapsulation has a type which may be an arbitrary lisp object. If a symbol has several encapsulations of different types, then any one of them can be removed without affecting more recent ones. A symbol may have more than one encapsulation of the same type, but only the most recent one can be undone.

Function: extensions:encapsulate symbol type body ¶

Saves the current definition of symbol, and replaces it with a function which returns the result of evaluating the form, body. Type is an arbitrary lisp object which is the type of encapsulation.

When the new function is called, the following variables are bound for the evaluation of body:

extensions:argument-list

A list of the arguments to the function.

extensions:basic-definition

The unencapsulated definition of the function.

The unencapsulated definition may be called with the original arguments by including the form

    (apply extensions:basic-definition extensions:argument-list)
  

encapsulate always returns symbol.

Function: extensions:unencapsulate symbol type ¶

Undoes symbol’s most recent encapsulation of type type. Type is compared with eq. Encapsulations of other types are left in place.

Function: extensions:encapsulated-p symbol type ¶

Returns t if symbol has an encapsulation of type type. Returns nil otherwise. type is compared with eq.

3.10.2 Tracing Examples

Here is an example of tracing with some of the possible options. For simplicity, this is the function:

    (defun fact (n)
      (declare (double-float n) (optimize speed))
      (if (zerop n)
          1d0
          (* n (fact (1- n)))))
    (compile 'fact)
  

This example shows how to use the :condition option:

    (trace fact :condition (= 4d0 (debug:arg 0)))
    (fact 10d0) ->
      0: (FACT 4.0d0)
      0: FACT returned 24.0d0
    3628800.0d0
  

As we can see, we produced output when the condition was satisfied.

Here’s another example:

    (untrace)
    (trace fact :break (= 4d0 (debug:arg 0)))
    (fact 10d0) ->
      0: (FACT 5.0d0)
        1: (FACT 4.0d0)


    Breaking before traced call to FACT:
       [Condition of type SIMPLE-CONDITION]

    Restarts:
      0: [CONTINUE] Return from BREAK.
      1: [ABORT   ] Return to Top-Level.

    Debug  (type H for help)
  

In this example, we see that normal tracing occurs until we the argument reaches 4d0, at which point, we break into the debugger.

4.3.1 Undefined Warnings

Warnings about undefined variables, functions and types are delayed until the end of the current compilation unit. The compiler entry functions (compile, etc.) implicitly use with-compilation-unit, so undefined warnings will be printed at the end of the compilation unless there is an enclosing with-compilation-unit. In order the gain the benefit of this mechanism, you should wrap a single with-compilation-unit around the calls to compile-file, i.e.:

(with-compilation-unit ()
  (compile-file "file1")
  (compile-file "file2")
  ...)

Unlike for functions and types, undefined warnings for variables are not suppressed when a definition (e.g. defvar) appears after the reference (but in the same compilation unit.) This is because doing special declarations out of order just doesn’t work—although early references will be compiled as special, bindings will be done lexically.

Undefined warnings are printed with full source context (see error-messages), which tremendously simplifies the problem of finding undefined references that resulted from macroexpansion. After printing detailed information about the undefined uses of each name, with-compilation-unit also prints summary listings of the names of all the undefined functions, types and variables.

Variable: *undefined-warning-limit* ¶

This variable controls the number of undefined warnings for each distinct name that are printed with full source context when the compilation unit ends. If there are more undefined references than this, then they are condensed into a single warning:

    Warning: count more uses of undefined function name.
  

When the value is 0, then the undefined warnings are not broken down by name at all: only the summary listing of undefined names is printed.

4.4.1 The Parts of the Error Message

The compiler will produce this warning:

File: /usr/me/stuff.lisp
In: DEFUN FOO
  (ZOQ Y)
--> ROQ PLOQ + 
==>
  Y
Warning: Result is a SYMBOL, not a NUMBER.

In this example we see each of the six possible parts of a compiler error message:

File: /usr/me/stuff.lisp

This is the file that the compiler read the relevant code from. The file name is displayed because it may not be immediately obvious when there is an error during compilation of a large system, especially when with-compilation-unit is used to delay undefined warnings.

In: DEFUN FOO

This is the definition or top-level form responsible for the error. It is obtained by taking the first two elements of the enclosing form whose first element is a symbol beginning with “DEF”. If there is no enclosing defmumble, then the outermost form is used. If there are multiple defmumbles, then they are all printed from the out in, separated by =>’s. In this example, the problem was in the defun for foo.

(ZOQ Y)

This is the original source form responsible for the error. Original source means that the form directly appeared in the original input to the compiler, i.e. in the lambda passed to compile or the top-level form read from the source file. In this example, the expansion of the zoq macro was responsible for the error.

--> ROQ PLOQ +

This is the processing path that the compiler used to produce the errorful code. The processing path is a representation of the evaluated forms enclosing the actual source that the compiler encountered when processing the original source. The path is the first element of each form, or the form itself if the form is not a list. These forms result from the expansion of macros or source-to-source transformation done by the compiler. In this example, the enclosing evaluated forms are the calls to roq, ploq and +. These calls resulted from the expansion of the zoq macro.

==> Y

This is the actual source responsible for the error. If the actual source appears in the explanation, then we print the next enclosing evaluated form, instead of printing the actual source twice. (This is the form that would otherwise have been the last form of the processing path.) In this example, the problem is with the evaluation of the reference to the variable y.

Warning: Result is a SYMBOL, not a NUMBER.

This is the explanation the problem. In this example, the problem is that y evaluates to a symbol, but is in a context where a number is required (the argument to +).

Note that each part of the error message is distinctively marked:

• File: and In: mark the file and definition, respectively.
• The original source is an indented form with no prefix.
• Each line of the processing path is prefixed with -->.
• The actual source form is indented like the original source, but is marked by a preceding ==> line. This is like the “macroexpands to” notation used in Common Lisp: The Language.
• The explanation is prefixed with the error severity (see error-severity), either Error:, Warning:, or Note:.

Each part of the error message is more specific than the preceding one. If consecutive error messages are for nearby locations, then the front part of the error messages would be the same. In this case, the compiler omits as much of the second message as in common with the first. For example:

File: /usr/me/stuff.lisp
In: DEFUN FOO
  (ZOQ Y)
--> ROQ 
==>
  (PLOQ (+ Y 3))
Warning: Undefined function: PLOQ

==>
  (ROQ (PLOQ (+ Y 3)))
Warning: Undefined function: ROQ

In this example, the file, definition and original source are identical for the two messages, so the compiler omits them in the second message. If consecutive messages are entirely identical, then the compiler prints only the first message, followed by:

[Last message occurs repeats times]

where repeats is the number of times the message was given.

If the source was not from a file, then no file line is printed. If the actual source is the same as the original source, then the processing path and actual source will be omitted. If no forms intervene between the original source and the actual source, then the processing path will also be omitted.

4.4.2 The Original and Actual Source

The original source displayed will almost always be a list. If the actual source for an error message is a symbol, the original source will be the immediately enclosing evaluated list form. So even if the offending symbol does appear in the original source, the compiler will print the enclosing list and then print the symbol as the actual source (as though the symbol were introduced by a macro.)

When the actual source is displayed (and is not a symbol), it will always be code that resulted from the expansion of a macro or a source-to-source compiler optimization. This is code that did not appear in the original source program; it was introduced by the compiler.

Keep in mind that when the compiler displays a source form in an error message, it always displays the most specific (innermost) responsible form. For example, compiling this function:

(defun bar (x)
  (let (a)
    (declare (fixnum a))
    (setq a (foo x))
    a))

gives this error message:

In: DEFUN BAR
  (LET (A) (DECLARE (FIXNUM A)) (SETQ A (FOO X)) A)
Warning: The binding of A is not a FIXNUM:
  NIL

This error message is not saying “there’s a problem somewhere in this let”—it is saying that there is a problem with the let itself. In this example, the problem is that a’s nil initial value is not a fixnum.

4.4.3 The Processing Path

The processing path is mainly useful for debugging macros, so if you don’t write macros, you can ignore the processing path. Consider this example:

(defun foo (n)
  (dotimes (i n *undefined*)))

Compiling results in this error message:

In: DEFUN FOO
  (DOTIMES (I N *UNDEFINED*))
--> DO BLOCK LET TAGBODY RETURN-FROM 
==>
  (PROGN *UNDEFINED*)
Warning: Undefined variable: *UNDEFINED*

Note that do appears in the processing path. This is because dotimes expands into:

(do ((i 0 (1+ i)) (#:g1 n))
    ((>= i #:g1) *undefined*)
  (declare (type unsigned-byte i)))

The rest of the processing path results from the expansion of do:

(block nil
  (let ((i 0) (#:g1 n))
    (declare (type unsigned-byte i))
    (tagbody (go #:g3)
     #:g2    (psetq i (1+ i))
     #:g3    (unless (>= i #:g1) (go #:g2))
             (return-from nil (progn *undefined*)))))

In this example, the compiler descended into the block, let, tagbody and return-from to reach the progn printed as the actual source. This is a place where the “actual source appears in explanation” rule was applied. The innermost actual source form was the symbol *undefined* itself, but that also appeared in the explanation, so the compiler backed out one level.

4.4.4 Error Severity

There are three levels of compiler error severity:

Error

This severity is used when the compiler encounters a problem serious enough to prevent normal processing of a form. Instead of compiling the form, the compiler compiles a call to error. Errors are used mainly for signaling syntax errors. If an error happens during macroexpansion, the compiler will handle it. The compiler also handles and attempts to proceed from read errors.

Warning

Warnings are used when the compiler can prove that something bad will happen if a portion of the program is executed, but the compiler can proceed by compiling code that signals an error at runtime if the problem has not been fixed:

• Violation of type declarations, or
• Function calls that have the wrong number of arguments or malformed keyword argument lists, or
• Referencing a variable declared ignore, or unrecognized declaration specifiers.

In the language of the Common Lisp standard, these are situations where the compiler can determine that a situation with undefined consequences or that would cause an error to be signaled would result at runtime.

Note

Notes are used when there is something that seems a bit odd, but that might reasonably appear in correct programs.

Note that the compiler does not fully conform to the proposed X3J13 cleanup “compiler-diagnostics”. Errors, warnings and notes mostly correspond to errors, warnings and style-warnings, but many things that the cleanup considers to be style-warnings are printed as warnings rather than notes. Also, warnings, style-warnings and most errors aren’t really signaled using the condition system.

4.4.5 Errors During Macroexpansion

The compiler handles errors that happen during macroexpansion, turning them into compiler errors. If you want to debug the error (to debug a macro), you can set *break-on-signals* to error. For example, this definition:

(defun foo (e l)
  (do ((current l (cdr current))
       ((atom current) nil))
      (when (eq (car current) e) (return current))))

gives this error:

In: DEFUN FOO
  (DO ((CURRENT L #) (# NIL)) (WHEN (EQ # E) (RETURN CURRENT)) )
Error: (during macroexpansion)

Error in function LISP::DO-DO-BODY.
DO step variable is not a symbol: (ATOM CURRENT)

4.4.6 Read Errors

The compiler also handles errors while reading the source. For example:

Error: Read error at 2:
 "(,/\foo)"
Error in function LISP::COMMA-MACRO.
Comma not inside a backquote.

The “at 2” refers to the character position in the source file at which the error was signaled, which is generally immediately after the erroneous text. The next line, “(,/\foo)”, is the line in the source that contains the error file position. The “/\” indicates the error position within that line (in this example, immediately after the offending comma.)

When in Hemlock (or any other EMACS-like editor), you can go to a character position with:

M-< C-u position C-f

Note that if the source is from a Hemlock buffer, then the position is relative to the start of the compiled region or defun, not the file or buffer start.

After printing a read error message, the compiler attempts to recover from the error by backing up to the start of the enclosing top-level form and reading again with *read-suppress* true. If the compiler can recover from the error, then it substitutes a call to cerror for the unreadable form and proceeds to compile the rest of the file normally.

If there is a read error when the file position is at the end of the file (i.e., an unexpected EOF error), then the error message looks like this:

Error: Read error in form starting at 14:
 "(defun test ()"
Error in function LISP::FLUSH-WHITESPACE.
EOF while reading #<Stream for file "/usr/me/test.lisp">

In this case, “starting at 14” indicates the character position at which the compiler started reading, i.e. the position before the start of the form that was missing the closing delimiter. The line "(defun test ()" is first line after the starting position that the compiler thinks might contain the unmatched open delimiter.

4.4.7 Error Message Parameterization

There is some control over the verbosity of error messages. See also undefined-warning-limit, *efficiency-note-limit* and efficiency-note-cost-threshold.

Variable: *enclosing-source-cutoff* ¶

This variable specifies the number of enclosing actual source forms that are printed in full, rather than in the abbreviated processing path format. Increasing the value from its default of 1 allows you to see more of the guts of the macroexpanded source, which is useful when debugging macros.

Variable: *error-print-length* ¶

Variable: *error-print-level* ¶

These variables are the print level and print length used in printing error messages. The default values are 5 and 3. If null, the global values of *print-level* and *print-length* are used.

Macro: extensions:def-source-context name lambda-list {form}* ¶

This macro defines how to extract an abbreviated source context from the named form when it appears in the compiler input. lambda-list is a defmacro style lambda-list used to parse the arguments. The body should return a list of subforms that can be printed on about one line. There are predefined methods for defstruct, defmethod, etc. If no method is defined, then the first two subforms are returned. Note that this facility implicitly determines the string name associated with anonymous functions.

4.5.1 Compile Time Type Errors

If the compiler can prove at compile time that some portion of the program cannot be executed without a type error, then it will give a warning at compile time. It is possible that the offending code would never actually be executed at run-time due to some higher level consistency constraint unknown to the compiler, so a type warning doesn’t always indicate an incorrect program. For example, consider this code fragment:

(defun raz (foo)
  (let ((x (case foo
             (:this 13)
             (:that 9)
             (:the-other 42))))
    (declare (fixnum x))
    (foo x)))

Compilation produces this warning:

In: DEFUN RAZ
  (CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42))
--> LET COND IF COND IF COND IF 
==>
  (COND)
Warning: This is not a FIXNUM:
  NIL

In this case, the warning is telling you that if foo isn’t any of :this, :that or :the-other, then x will be initialized to nil, which the fixnum declaration makes illegal. The warning will go away if ecase is used instead of case, or if :the-other is changed to t.

This sort of spurious type warning happens moderately often in the expansion of complex macros and in inline functions. In such cases, there may be dead code that is impossible to correctly execute. The compiler can’t always prove this code is dead (could never be executed), so it compiles the erroneous code (which will always signal an error if it is executed) and gives a warning.

Function: extensions:required-argument ¶

This function can be used as the default value for keyword arguments that must always be supplied. Since it is known by the compiler to never return, it will avoid any compile-time type warnings that would result from a default value inconsistent with the declared type. When this function is called, it signals an error indicating that a required keyword argument was not supplied. This function is also useful for defstruct slot defaults corresponding to required arguments. See empty-type.

Although this function is a CMUCL extension, it is relatively harmless to use it in otherwise portable code, since you can easily define it yourself:

    (defun required-argument ()
      (error "A required keyword argument was not supplied."))
    

Type warnings are inhibited when the extensions:inhibit-warnings optimization quality is 3 (see compiler-policy.) This can be used in a local declaration to inhibit type warnings in a code fragment that has spurious warnings.

4.5.2 Precise Type Checking

With the default compilation policy, all type assertions⁶ are precisely checked. Precise checking means that the check is done as though typep had been called with the exact type specifier that appeared in the declaration. Python uses policy to determine whether to trust type assertions (see compiler-policy). Type assertions from declarations are indistinguishable from the type assertions on arguments to built-in functions. In Python, adding type declarations makes code safer.

If a variable is declared to be (integer 3 17), then its value must always always be an integer between 3 and 17. If multiple type declarations apply to a single variable, then all the declarations must be correct; it is as though all the types were intersected producing a single and type specifier.

Argument type declarations are automatically enforced. If you declare the type of a function argument, a type check will be done when that function is called. In a function call, the called function does the argument type checking, which means that a more restrictive type assertion in the calling function (e.g., from the) may be lost.

The types of structure slots are also checked. The value of a structure slot must always be of the type indicated in any :type slot option.⁷ Because of precise type checking, the arguments to slot accessors are checked to be the correct type of structure.

In traditional Common Lisp compilers, not all type assertions are checked, and type checks are not precise. Traditional compilers blindly trust explicit type declarations, but may check the argument type assertions for built-in functions. Type checking is not precise, since the argument type checks will be for the most general type legal for that argument. In many systems, type declarations suppress what little type checking is being done, so adding type declarations makes code unsafe. This is a problem since it discourages writing type declarations during initial coding. In addition to being more error prone, adding type declarations during tuning also loses all the benefits of debugging with checked type assertions.

To gain maximum benefit from Python’s type checking, you should always declare the types of function arguments and structure slots as precisely as possible. This often involves the use of or, member and other list-style type specifiers. Paradoxically, even though adding type declarations introduces type checks, it usually reduces the overall amount of type checking. This is especially true for structure slot type declarations.

Python uses the safety optimization quality (rather than presence or absence of declarations) to choose one of three levels of run-time type error checking: see optimize-declaration. See advanced-type-stuff for more information about types in Python.