Chapter 2 Design Choices and
Extensions
Several design choices in Common Lisp are left to the individual
implementation, and some essential parts of the programming
environment are left undefined. This chapter discusses the most
important design choices and extensions.
2.1 Data Types
The fixnum type is
equivalent to (signed-byte 30). Integers
outside this range are represented as a bignum or a word integer (see
section 5.11.6.) Almost all integers
that appear in programs can be represented as a fixnum, so integer number consing is rare.
CMUCL supports two
floating point formats: single-float and double-float. These are implemented with IEEE single
and double float arithmetic, respectively. 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 section 5.11.)
2.1.2.1 IEEE Special
Values
CMUCL supports the IEEE infinity and NaN special values. These
non-numeric values will only be generated when trapping is disabled
for some floating point exception (see section 2.1.2.4), so users of the default configuration
need not concern themselves with special values.
[Constant]
extensions:short-float-positive-infinity
[Constant]
extensions:short-float-negative-infinity
[Constant]
extensions:single-float-positive-infinity
[Constant]
extensions:single-float-negative-infinity
[Constant]
extensions:double-float-positive-infinity
[Constant]
extensions:double-float-negative-infinity
[Constant]
extensions:long-float-positive-infinity
[Constant]
extensions:long-float-negative-infinity
The values of these constants are the IEEE positive and negative
infinity objects for each float format.
[Function]
extensions:float-infinity-p x
This function returns true if x is an
IEEE float infinity (of either sign.) x
must be a float.
[Function]
extensions:float-nan-p x
[Function]
extensions:float-trapping-nan-p x
float-nan-p returns true if x is an IEEE NaN (Not A Number) object. float-trapping-nan-p returns true only if x is a trapping NaN. With either function,
x must be a float.
2.1.2.2 Negative Zero
The IEEE float format provides for distinct positive and negative
zeros. To test the sign on zero (or any other float), use the
Common Lisp float-sign
function. Negative zero prints as -0.0f0 or
-0.0d0.
2.1.2.3 Denormalized
Floats
CMUCL supports IEEE denormalized floats. Denormalized floats
provide a mechanism for gradual underflow. The Common Lisp float-precision function returns
the actual precision of a denormalized float, which will be less
than float-digits. Note
that in order to generate (or even print) denormalized floats,
trapping must be disabled for the underflow exception (see
section 2.1.2.4.) The Common Lisp
least-positive-format-float constants are
denormalized.
[Function]
extensions:float-denormalized-p x
This function returns true if x is a
denormalized float. x must be a
float.
2.1.2.4 Floating Point
Exceptions
The IEEE floating point
standard defines several exceptions that occur when the result of a
floating point operation is unclear or undesirable. Exceptions can
be ignored, in which case some default action is taken, such as
returning a special value. When trapping is enabled for an
exception, a error is signalled whenever that exception occurs.
These are the possible floating point exceptions:
- :underflow
- This exception occurs when the result of an
operation is too small to be represented as a normalized float in
its format. If trapping is enabled, the floating-point-underflow
condition is signalled. Otherwise, the operation results in a
denormalized float or zero.
- :overflow
- This exception occurs when the result of an
operation is too large to be represented as a float in its format.
If trapping is enabled, the floating-point-overflow exception is signalled.
Otherwise, the operation results in the appropriate infinity.
- :inexact
- This exception occurs when the result of a
floating point operation is not exact, i.e. the result was rounded.
If trapping is enabled, the extensions:floating-point-inexact condition is
signalled. Otherwise, the rounded result is returned.
- :invalid
- This exception occurs when the result of an
operation is ill-defined, such as (/ 0.0
0.0). If trapping is enabled, the extensions:floating-point-invalid condition is
signalled. Otherwise, a quiet NaN is returned.
- :divide-by-zero
- This exception occurs when a float is divided
by zero. If trapping is enabled, the divide-by-zero condition is
signalled. Otherwise, the appropriate infinity is returned.
2.1.2.5 Floating Point
Rounding Mode
IEEE
floating point specifies four possible rounding modes:
- :nearest
- In this mode, the inexact results are rounded
to the nearer of the two possible result values. If the neither
possibility is nearer, then the even alternative is chosen. This
form of rounding is also called “round to even”, and is
the form of rounding specified for the Common Lisp round function.
- :positive-infinity
- This mode rounds inexact results to the
possible value closer to positive infinity. This is analogous to
the Common Lisp ceiling
function.
- :negative-infinity
- This mode rounds inexact results to the
possible value closer to negative infinity. This is analogous to
the Common Lisp floor
function.
- :zero
- This mode rounds inexact results to the
possible value closer to zero. This is analogous to the Common Lisp
truncate function.
Warning:
Although the rounding mode can be changed with set-floating-point-modes, use of any value other than
the default (:nearest) can cause unusual
behavior, since it will affect rounding done by Common Lisp system
code as well as rounding in user code. In particular, the unary
round function will stop doing
round-to-nearest on floats, and instead do the selected form of
rounding.
2.1.2.6 Precision Control
The
floating-point unit for the Intel IA-32 architecture supports a
precision control mechanism. The floating-point unit consists of an
IEEE extended double-float unit and all operations are always done
using his format, and this includes rounding. However, by setting
the precision control mode, the user can control how rounding is
done for each basic arithmetic operation like addition,
subtraction, multiplication, and division. The extra instructions
for trigonometric, exponential, and logarithmic operations are not
affected. We refer the reader to Intel documentation for more
information.
The possible modes are:
- :24-bit
- In this mode, all basic arithmetic operations
like addition, subtraction, multiplication, and division, are
rounded after each operation as if both the operands were IEEE
single precision numbers.
- :53-bit
- In this mode, rounding is performed as if the
operands and results were IEEE double precision numbers.
- :64-bit
- In this mode, the default, rounding is
performed on the full IEEE extended double precision format.
Warning:
Although the precision mode can be changed with set-floating-point-modes, use of anything other than
:64-bit or :53-bit can
cause unexpected results, especially if external functions or
libraries are called. A setting of :64-bit
also causes (= 1d0 (+ 1d0
double-float-epsilon)) to return t
instead of nil.
2.1.2.7 Accessing the Floating
Point Modes
These functions can be used to modify or read the floating point
modes:
[Function]
extensions:set-floating-point-modes &key :traps :rounding-mode
:fast-mode :accrued-exceptions
:current-exceptions :precision-control
[Function]
extensions:get-floating-point-modes
The keyword arguments to set-floating-point-modes set various modes controlling
how floating point arithmetic is done:
- :traps
- A list of the exception conditions that should
cause traps. Possible exceptions are :underflow, :overflow, :inexact, :invalid and :divide-by-zero. Initially all traps except :inexact are enabled. See section 2.1.2.4.
- :rounding-mode
- The rounding mode to use when the result is not
exact. Possible values are :nearest,
:positive-infinity, :negative-infinity and :zero.
Initially, the rounding mode is :nearest. See
the warning in section 2.1.2.5
about use of other rounding modes.
- :current-exceptions,
:accrued-exceptions
- Lists of exception keywords used to set the
exception flags. The current-exceptions
are the exceptions for the previous operation, so setting it is not
very useful. The accrued-exceptions are a
cumulative record of the exceptions that occurred since the last
time these flags were cleared. Specifying ()
will clear any accrued exceptions.
- :fast-mode
- Set the hardware's “fast mode”
flag, if any. When set, IEEE conformance or debuggability may be
impaired. Some machines may not have this feature, in which case
the value is always nil. Sparc platforms
support a fast mode where denormal numbers are silently truncated
to zero.
- :precision-control
- On the x86 architecture, you can set the
precision of the arithmetic to :24-bit,
:53-bit, or :64-bit
mode, corresponding to IEEE single precision, double precision, and
extended double precision.
If a keyword argument is not supplied, then the associated state is
not changed.
get-floating-point-modes returns a list
representing the state of the floating point modes. The list is in
the same format as the keyword arguments to set-floating-point-modes, so apply could be used with set-floating-point-modes to restore the modes in effect
at the time of the call to get-floating-point-modes.
To make handling control of floating-point exceptions, the
following macro is useful.
[Macro]
ext:with-float-traps-masked traps &body body
body is executed
with the selected floating-point exceptions given by traps masked out (disabled). traps should be a list of possible floating-point
exceptions that should be ignored. Possible values are :underflow, :overflow, :inexact, :invalid and :divide-by-zero.
This is equivalent to saving the current traps from get-floating-point-modes, setting the floating-point
modes to the desired exceptions, running the body, and restoring the saved floating-point modes. The
advantage of this macro is that it causes less consing to
occur.
Some points about the with-float-traps-masked:
- Two approaches are available for detecting
FP exceptions:
- enabling the traps and handling the
exceptions
- disabling the traps and either handling
the return values or checking the accrued exceptions.
Of these the latter is the most portable because on the alpha port
it is not possible to enable some traps at run-time.
- To assist the checking of the exceptions
within the body any accrued exceptions matching the given traps are
cleared at the start of the body when the traps are masked.
- To allow the macros to be nested these
accrued exceptions are restored at the end of the body to their
values at the start of the body. Thus any exceptions that occurred
within the body will not affect the accrued exceptions outside the
macro.
- Note that only the given exceptions are
restored at the end of the body so other exception will be visible
in the accrued exceptions outside the body.
- On the x86, setting the accrued exceptions
of an unmasked exception would cause a FP trap. The macro behaviour
of restoring the accrued exceptions ensures than if an accrued
exception is initially not flagged and occurs within the body it
will be restored/cleared at the exit of the body and thus not cause
a trap.
- On the x86, and, perhaps, the hppa, the FP
exceptions may be delivered at the next FP instruction which
requires a FP wait instruction (x86::float-wait) if using the lisp conditions to catch
trap within a handler-bind. The handler-bind macro does the right thing and inserts a
float-wait (at the end of its body on the x86). The masking and
noting of exceptions is also safe here.
- The setting of the FP flags uses the
(floating-point-modes) and the (set (floating-point-modes)...) VOPs. These VOPs
blindly update the flags which may include other state. We assume
this state hasn't changed in between getting and setting the state.
For example, if you used the FP unit between the above calls, the
state may be incorrectly restored! The with-float-traps-masked macro keeps the intervening
code to a minimum and uses only integer operations.
2.1.3 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.) Character codes range between 0 and 255, using the ASCII
encoding. Table 2.1 tbl:chars
shows characters recognized by CMUCL.
ASCII |
Lisp |
|
Name |
Code |
Name |
1.5exAlternatives |
nul |
0 |
#\NULL |
#\NUL |
|
|
bel |
7 |
#\BELL |
|
|
|
bs |
8 |
#\BACKSPACE |
#\BS |
|
|
tab |
9 |
#\TAB |
|
|
|
lf |
10 |
#\NEWLINE |
#\NL |
#\LINEFEED |
#\LF |
ff |
11 |
#\VT |
#\PAGE |
#\FORM |
|
cr |
13 |
#\RETURN |
#\CR |
|
|
esc |
27 |
#\ESCAPE |
#\ESC |
#\ALTMODE |
#\ALT |
sp |
32 |
#\SPACE |
#\SP |
|
|
del |
127 |
#\DELETE |
#\RUBOUT |
|
|
Table 2.1: Characters recognized by CMUCL
2.1.4 Array Initialization
If no :initial-value is specified, arrays are
initialized to zero.
2.1.5 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.
2.2 Default Interrupts for Lisp
CMUCL has several interrupt handlers defined when it starts up, as
follows:
- SIGINT (Ctrl-c)
- causes Lisp to enter a break loop. This puts
you into the debugger which allows you to look at the current state
of the computation. If you proceed from the break loop, the
computation will proceed from where it was interrupted.
- SIGQUIT (Ctrl-L)
- causes Lisp to do a throw to the top-level.
This causes the current computation to be aborted, and control
returned to the top-level read-eval-print loop.
- SIGTSTP (Ctrl-z)
- causes Lisp to suspend execution and return to
the Unix shell. If control is returned to Lisp, the computation
will proceed from where it was interrupted.
- SIGILL, SIGBUS, SIGSEGV, and SIGFPE
- cause Lisp to signal an error.
For keyboard interrupt signals, the standard interrupt character is
in parentheses. Your .login may set up
different interrupt characters. When a signal is generated, there
may be some delay before it is processed since Lisp cannot be
interrupted safely in an arbitrary place. The computation will
continue until a safe point is reached and then the interrupt will
be processed. See section 6.8.1 to define your own signal
handlers.
2.3 Implementation-specific Packages
When CMUCL is first started up, the default package is the
common-lisp-user package. The common-lisp-user package uses the common-lisp and extensions
packages. The symbols exported from these three packages can be
referenced without package qualifiers. This section describes
packages which have exported interfaces that may concern users. The
numerous internal packages which implement parts of the system are
not described here. Package nicknames are in parenthesis after the
full name.
- alien, c-call
- Export the features of the Alien foreign data
structure facility (see section 8.)
- pcl
- This package contains PCL (Portable
CommonLoops), which is a portable implementation of CLOS (the
Common Lisp Object System.) This implements most (but not all) of
the features in the CLOS chapter of Common Lisp: The Language
II.
- clos-mop (mop)
- This package contains an implementation of the
CLOS Metaobject Protocol, as per the book The Art of the
Metaobject Protocol.
- debug
- The debug package
contains the command-line oriented debugger. It exports utility
various functions and switches.
- debug-internals
- The debug-internals
package exports the primitives used to write debuggers. See
section 11.
- extensions (ext)
- The extensions packages
exports local extensions to Common Lisp that are documented in this
manual. Examples include the save-lisp
function and time parsing.
- hemlock (ed)
- The hemlock package
contains all the code to implement Hemlock commands. The hemlock package currently exports no symbols.
- hemlock-internals
(hi)
- The hemlock-internals
package contains code that implements low level primitives and
exports those symbols used to write Hemlock commands.
- keyword
- The keyword package
contains keywords (e.g., :start). All symbols
in the keyword package are exported and
evaluate to themselves (i.e., the value of the symbol is the symbol
itself).
- profile
- The profile package
exports a simple run-time profiling facility (see
section 5.14).
- common-lisp (cl)
- The common-lisp package
exports all the symbols defined by Common Lisp: The Language
and only those symbols. Strictly portable Lisp code will depend
only on the symbols exported from the common-lisp package.
- unix
- This package exports system call interfaces to
Unix (see section 6).
- system (sys)
- The system package
contains functions and information necessary for system
interfacing. This package is used by the lisp
package and exports several symbols that are necessary to interface
to system code.
- xlib
- The xlib package contains
the Common Lisp X interface (CLX) to the X11 protocol. This is
mostly Lisp code with a couple of functions that are defined in C
to connect to the server.
- wire
- The wire package exports
a remote procedure call facility (see section 9).
- stream
- The stream package
exports the public interface to the simple-streams implementation
(see section 2.13).
2.4 Hierarchical Packages
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 packages named foo
,
foo.bar
, mypack
, mypack.foo
,
mypack.foo.bar
, mypack.foo.baz
,
mypack.bar
, and mypack.bar.baz
, have all
been created.
relative name |
current package |
absolute name of referenced package |
foo |
any |
foo |
foo.bar |
any |
foo.bar |
.foo |
mypack |
mypack.foo |
.foo.bar |
mypack |
mypack.foo.bar |
..foo |
mypack.bar |
mypack.foo |
..foo.baz |
mypack.bar |
mypack.foo.baz |
...foo |
mypack.bar.baz |
mypack.foo |
. |
mypack.bar.baz |
mypack.bar.baz |
.. |
mypack.bar.baz |
mypack.bar |
... |
mypack.bar.baz |
mypack |
Table 2.2: Examples of hierarchical
packages
Additional notes:
- All packages in the hierarchy must
exist.
- 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 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.
- 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.
2.4.3.1 Changes to cl:find-package
Using relative hierarchical package names requires a simple
modification of cl:find-package.
In ANSI Common Lisp, cl:find-package, if
passed a package object, returns it; if passed a string, cl:find-package looks for a package with that string as
its name or nickname, and returns the package if it finds one, or
returns nil if it does not; if passed a symbol, the symbol name (a
string) is extracted and cl:find-package
proceeds as it does with a string.
For implementing hierarchical packages, the behavior when the
argument is a package object (return it) does not change. But when
the argument is a string starting with one or more dots not
directly naming a package, cl:find-package
will, instead of returning nil, check whether the string can be
resolved as naming a relative package, and if so, return the
associated absolute package object. (If the argument is a symbol,
the symbol name is extracted and cl:find-package proceeds as it does with a string
argument.)
Note that you should not use leading dots in package names when
using hierarchical packages.
2.4.3.2 Using hierarchical
packages without modifying cl:find-package
Even without the modifications to cl:find-package, authors need not avoid using relative
package names, but the ability to reuse relative package names is
restricted. Consider for example a module foo which is
composed of the my.foo.bar
and my.foo.baz
packages. In the code for each of the these packages there are
relative package references, ..bar
and
..baz
.
Implementations that have the new cl:find-package would carry the keyword
:relative-package-names
on their *features* list (this is the case of CMUCL releases
starting from 18d). Then, in the foo module, there would be
definitions of the my.foo.bar
and
my.foo.baz
packages like so:
(defpackage :my.foo.bar
#-relative-package-names (:nicknames #:..bar)
...)
(defpackage :my.foo.baz
#-relative-package-names (:nicknames #:..baz)
...)
Then, in a #-relative-package-names
implementation,
the symbol my.foo.bar:blam
would be visible from
my.foo.baz
as ..bar:blam
, just as it
would from a #+relative-package-names
implementation.
So, even without the implementation of the augmented cl:find-package, one can still write Common Lisp code
that will work in both types of implementations, but
..bar
and ..baz
are now used, so you
cannot also have otherpack.foo.bar
and
otherpack.foo.baz
and use ..bar
and
..baz
as relative names. (The point of hierarchical
packages, of course, is to allow reusing relative package
names.)
2.5 Package locks
CMUCL provides two types of package locks,
as an extension to the ANSI Common Lisp standard. The package-lock
protects a package from changes in its structure (the set of
exported symbols, its use list, etc). The package-definition-lock
protects the symbols in the package from being redefined due to the
execution of a defun, defmacro, defstruct, deftype or defclass form.
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.6 The Editor
The ed function invokes the Hemlock editor
which is described in Hemlock User's Manual and Hemlock
Command Implementor's Manual. Most users at CMU prefer to use
Hemlock's slave Common Lisp mechanism which provides an interactive
buffer for the read-eval-print loop and
editor commands for evaluating and compiling text from a buffer
into the slave Common Lisp. Since the editor runs in the Common
Lisp, using slaves keeps users from trashing their editor by
developing in the same Common Lisp with Hemlock.
2.7 Garbage Collection
CMUCL uses either a stop-and-copy garbage collector or a
generational, mostly copying garbage collector. Which collector is
available depends on the platform and the features of the platform.
The stop-and-copy GC is available on all RISC platforms. The x86
platform supports a conservative stop-and-copy collector, which is
now rarely used, and a generational conservative collector. On the
Sparc platform, both the stop-and-copy GC and the generational GC
are available, but the stop-and-copy GC is deprecated in favor of
the generational GC.
The generational GC is available if *features* contains :gencgc.
The following functions invoke the garbage collector or control
whether automatic garbage collection is in effect:
[Function]
[- c
heney]extensions:gc&optional verbose-p
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-p indicates whether GC statistics are
printed or not.
[Function]
extensions:gc-off
This function inhibits automatic garbage collection. After calling
it, the system will not GC unless you call ext:gc or ext:gc-on.
[Function]
extensions:gc-on
This function reinstates automatic garbage collection. If the
system would have GC'ed while automatic GC was inhibited, then this
will call ext:gc.
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]
[- g
encgc]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:
- Bytes allocated in this generation
- The GC trigger for this generation. When
this many bytes have been allocated, a GC is started
automatically.
- The number of bytes consed between
GCs.
- The number of GCs that have been done on
this generation. This is reset to zero when the generation is
raised.
- The trigger age, which is the maximum
number of GCs to perform before this generation is raised.
- The total number of bytes allocated to
this generation.
- 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.8 Describe
[Function]
describe object &optional stream
The describe function prints useful
information about object on stream, which defaults to *standard-output*. For any object, describe will print out the type. Then it prints other
information based on the type of object.
The types which are presently handled are:
- hash-table
- describe prints the
number of entries currently in the hash table and the number of
buckets currently allocated.
- function
- describe prints a list of
the function's name (if any) and its formal parameters. If the name
has function documentation, then it will be printed. If the
function is compiled, then the file where it is defined will be
printed as well.
- fixnum
- describe prints whether
the integer is prime or not.
- symbol
- The symbol's value, properties, and
documentation are printed. If the symbol has a function definition,
then the function is described.
If there is anything interesting to be said about some component of
the object, describe will invoke itself recursively to describe
that object. The level of recursion is indicated by indenting
output.
A number of switches can be used to control describe's behavior.
[Variable]
extensions:*describe-level*
The maximum level of recursive description allowed. Initially
two.
[Variable]
extensions:*describe-indentation*
The number of spaces to indent for each level of recursive
description, initially three.
[Variable]
extensions:*describe-print-level*
[Variable]
extensions:*describe-print-length*
The values of *print-level* and *print-length* during description. Initially two and
five.
2.9 The Inspector
CMUCL has both a graphical inspector that uses the X Window System,
and a simple terminal-based inspector.
[Function]
inspect &optional object
inspect calls the inspector on the optional
argument object. If object is unsupplied, inspect
immediately returns nil. Otherwise, the
behavior of inspect depends on whether Lisp is running under X.
When inspect is eventually exited, it returns
some selected Lisp 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.
[Function]
load filename &key :verbose :print :if-does-not-exist
:if-source-newer :contents
As in standard Common Lisp, this function loads a file containing
source or object code into the running Lisp. Several CMU extensions
have been made to load to conveniently
support a variety of program file organizations. filename may be a wildcard pathname such as
*.lisp, in which case all matching files
are loaded.
If filename has a pathname-type (or extension), then that exact file is
loaded. If the file has no extension, then this tells load to use a heuristic to load the “right”
file. The *load-source-types* and *load-object-types* variables below are used to
determine the default source and object file types. If only the
source or the object file exists (but not both), then that file is
quietly loaded. Similarly, if both the source and object file
exist, and the object file is newer than the source file, then the
object file is loaded. The value of the if-source-newer argument is used to determine what
action to take when both the source and object files exist, but the
object file is out of date:
- :load-object
- The object file is loaded even though the
source file is newer.
- :load-source
- The source file is loaded instead of the older
object file.
- :compile
- The source file is compiled and then the new
object file is loaded.
- :query
- The user is asked a yes or no question to
determine whether the source or object file is loaded.
This argument defaults to the value of ext:*load-if-source-newer* (initially :load-object.)
The contents argument can be used to
override the heuristic (based on the file extension) that normally
determines whether to load the file as a source file or an object
file. If non-null, this argument must be either :source or :binary, which forces
loading in source and binary mode, respectively. You really
shouldn't ever need to use this argument.
[Variable]
extensions:*load-source-types*
[Variable]
extensions:*load-object-types*
These variables are lists of possible pathname-type values for source and object files to be
passed to load. These variables are only used
when the file passed to load has no type; in
this case, the possible source and object types are used to default
the type in order to determine the names of the source and object
files.
[Variable]
extensions:*load-if-source-newer*
This variable determines the default value of the if-source-newer argument to load. Its initial value is :load-object.
2.11 The Reader
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.12 Stream Extensions
[Function]
sys:read-n-bytes stream
buffer start numbytes &optional
eof-error-p
On streams that support it, this function reads multiple bytes of
data into a buffer. The buffer must be a simple-string or (simple-array
(unsigned-byte 8) (*)). The argument nbytes specifies the desired number of bytes, and
the return value is the number of bytes actually read.
- If eof-error-p is
true, an end-of-file
condition is signalled if end-of-file is encountered before
count bytes have been read.
- If eof-error-p is
false, read-n-bytes reads as much data is
currently available (up to count bytes.) On pipes or similar
devices, this function returns as soon as any data is available,
even if the amount read is less than count and eof has not been hit. See also make-fd-stream.
2.13 Simple Streams
CMUCL includes a partial implementation of
Simple Streams, a protocol that allows user-extensible
streams. The protocol was proposed by Franz, Inc. and is intended
to replace the Gray Streams method of extending streams.
Simple streams are distributed as a CMUCL subsystem, that can be
loaded into the image by saying
(require :simple-streams)
Note that CMUCL's implementation of simple streams is incomplete,
and in particular is currently missing support for the functions
read-sequence and write-sequence. Please consult the Allegro Common
Lisp documentation for more information on simple streams.
2.14 Running Programs from Lisp
It is possible to run programs from Lisp by using the following
function.
[Function]
extensions:run-program program
args &key
:env :wait :pty :input
:if-input-does-not-exist
:output :if-output-exists
:error :if-error-exists
:status-hook :before-execve
run-program runs program in a child process. Program should be a pathname or string naming the
program. Args should be a list of strings
which this passes to program as normal
Unix parameters. For no arguments, specify args as nil. The value
returned is either a process structure or nil. The process interface follows the description of
run-program. If run-program fails to fork the child process, it returns
nil.
Except for sharing file descriptors as explained in keyword
argument descriptions, run-program closes all
file descriptors in the child process before running the program.
When you are done using a process, call process-close to reclaim system resources. You only
need to do this when you supply :stream for
one of :input, :output,
or :error, or you supply :pty non-nil. You can call
process-close regardless of whether you must
to reclaim resources without penalty if you feel safer.
run-program accepts the following keyword
arguments:
- :env
- This is an a-list mapping keywords and
simple-strings. The default is ext:*environment-list*. If :env
is specified, run-program uses the value
given and does not combine the environment passed to Lisp with the
one specified.
- :wait
- If non-nil (the default),
wait until the child process terminates. If nil, continue running Lisp while the child process
runs.
- :pty
- This should be one of t,
nil, or a stream. If specified non-nil, the subprocess executes under a Unix PTY. If
specified as a stream, the system collects all output to this pty
and writes it to this stream. If specified as t, the process-pty slot contains
a stream from which you can read the program's output and to which
you can write input for the program. The default is nil.
- :input
- This specifies how the program gets its input.
If specified as a string, it is the name of a file that contains
input for the child process. run-program
opens the file as standard input. If specified as nil (the default), then standard input is the file
/dev/null. If specified as t, the program uses the current standard input. This
may cause some confusion if :wait is
nil since two processes may use the terminal
at the same time. If specified as :stream,
then the process-input slot contains an
output stream. Anything written to this stream goes to the program
as input. :input may also be an input stream
that already contains all the input for the process. In this case
run-program reads all the input from this
stream before returning, so this cannot be used to interact with
the process.
- :if-input-does-not-exist
- This specifies what to do if the input file
does not exist. The following values are valid: nil (the default) causes run-program to return nil without
doing anything; :create creates the named
file; and :error signals an error.
- :output
- This specifies what happens with the program's
output. If specified as a pathname, it is the name of a file that
contains output the program writes to its standard output. If
specified as nil (the default), all output
goes to /dev/null. If specified as
t, the program writes to the Lisp process's
standard output. This may cause confusion if :wait is nil since two processes
may write to the terminal at the same time. If specified as
:stream, then the process-output slot contains an input stream from which
you can read the program's output.
- :if-output-exists
- This specifies what to do if the output file
already exists. The following values are valid: nil causes run-program to return
nil without doing anything; :error (the default) signals an error; :supersede overwrites the current file; and :append appends all output to the file.
- :error
- This is similar to :output, except the file becomes the program's standard
error. Additionally, :error can be :output in which case the program's error output is
routed to the same place specified for :output. If specified as :stream,
the process-error contains a stream similar
to the process-output slot when specifying
the :output argument.
- :if-error-exists
- This specifies what to do if the error output
file already exists. It accepts the same values as :if-output-exists.
- :status-hook
- This specifies a function to call whenever the
process changes status. This is especially useful when specifying
:wait as nil. The
function takes the process as a required argument.
- :before-execve
- This specifies a function to run in the child
process before it becomes the program to run. This is useful for
actions such as authenticating the child process without modifying
the parent Lisp process.
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.15 Saving a Core Image
A mechanism has been provided to save a running Lisp core image and
to later restore it. This is convenient if you don't want to load
several files into a Lisp when you first start it up. The main
problem is the large size of each saved Lisp image, typically at
least 20 megabytes.
[Function]
extensions:save-lisp file
&key :purify
:root-structures :init-function
:load-init-file :print-herald :site-init
:process-command-line :batch-mode
The save-lisp function saves the state of the
currently running Lisp core image in file. The keyword arguments have the following
meaning:
- :purify
- If non-nil (the default),
the core image is purified before it is saved (see purify.) This reduces the
amount of work the garbage collector must do when the resulting
core image is being run. Also, if more than one Lisp is running on
the same machine, this maximizes the amount of memory that can be
shared between the two processes.
- :root-structures
- This should be a list of the main entry points
in any newly loaded systems. This need not be supplied, but
locality and/or GC performance will be better if they are.
Meaningless if :purify is nil. See purify.
- :init-function
- This is the function that starts running when
the created core file is resumed. The default function simply
invokes the top level read-eval-print loop. If the function returns
the lisp will exit.
- :load-init-file
- If non-NIL, then load an init file; either the
one specified on the command line or “init.fasl-type”,
or, if “init.fasl-type” does not exist, init.lisp from the user's home directory. If the init
file is found, it is loaded into the resumed core file before the
read-eval-print loop is entered.
- :site-init
- If non-NIL, the name of the site init file to
quietly load. The default is library:site-init. No error is signalled if the
file does not exist.
- :print-herald
- If non-NIL (the default), then print out the
standard Lisp herald when starting.
- :process-command-line
- If non-NIL (the default), processes the command
line switches and performs the appropriate actions.
- :batch-mode
- If NIL (the default), then the presence of the
-batch command-line switch will invoke batch-mode processing upon
resuming the saved core. If non-NIL, the produced core will always
be in batch-mode, regardless of any command-line switches.
To resume a saved file, type:
lisp -core file
[Function]
extensions:purify file
&key :root-structures :environment-name
This function optimizes garbage collection by moving all currently
live objects into non-collected storage. Once statically allocated,
the objects can never be reclaimed, even if all pointers to them
are dropped. This function should generally be called after a large
system has been loaded and initialized.
- :root-structures
- is an optional list of objects which should be
copied first to maximize locality. This should be a list of the
main entry points for the resulting core image. The purification
process tries to localize symbols, functions, etc., in the core
image so that paging performance is improved. The default value is
NIL which means that Lisp objects will still be localized but
probably not as optimally as they could be.
defstruct structures defined with the
(:pure t) option are moved into read-only
storage, further reducing GC cost. List and vector slots of pure
structures are also moved into read-only storage.
- :environment-name
- is gratuitous documentation for the compacted
version of the current global environment (as seen in c::*info-environment*.) If nil is
supplied, then environment compaction is inhibited.
2.16 Pathnames
In Common Lisp quite a few aspects of pathname semantics are left to
the implementation.
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, :NEWEST
(parse "foo.bar") ==> "foo", "bar", :NEWEST
(parse ".foo") ==> ".foo", NIL, :NEWEST
(parse ".foo.bar") ==> ".foo", "bar", :NEWEST
(parse "..") ==> ".", "", :NEWEST
(parse "foo.") ==> "foo", "", :NEWEST
(parse "foo.bar.1") ==> "foo", "bar", 1
(parse "foo.bar.baz") ==> "foo.bar", "baz", :NEWEST
The directory of pathnames beginning with a slash (or a
search-list, see section 2.16.4)
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 section 2.16.3) matches any number of directory
parts with `**' (see see
section 2.17.1.)
`*' 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
section 2.16.4) 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.)
- target:
- The root of the tree where CMUCL was
compiled.
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 Filesystem Operations
CMUCL provides a number of extensions and optional features beyond
those required by the Common Lisp specification.
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.18 Time Parsing and Formatting
Functions are
provided to allow parsing strings containing time information and
printing time in various formats are available.
[Function]
extensions:parse-time time-string &key
:error-on-mismatch :default-seconds
:default-minutes :default-hours
:default-day :default-month
:default-year :default-zone
:default-weekday
parse-time accepts a string containing a time
(e.g., "Jan 12, 1952") and returns the
universal time if it is successful. If it is unsuccessful and the
keyword argument :error-on-mismatch is
non-nil, it signals an error. Otherwise it
returns nil. The other keyword arguments have
the following meaning:
- :default-seconds
- specifies the default value for the seconds
value if one is not provided by time-string. The default value is 0.
- :default-minutes
- specifies the default value for the minutes
value if one is not provided by time-string. The default value is 0.
- :default-hours
- specifies the default value for the hours value
if one is not provided by time-string.
The default value is 0.
- :default-day
- specifies the default value for the day value
if one is not provided by time-string.
The default value is the current day.
- :default-month
- specifies the default value for the month value
if one is not provided by time-string.
The default value is the current month.
- :default-year
- specifies the default value for the year value
if one is not provided by time-string.
The default value is the current year.
- :default-zone
- specifies the default value for the time zone
value if one is not provided by time-string. The default value is the current time
zone.
- :default-weekday
- specifies the default value for the day of the
week if one is not provided by time-string. The default value is the current day
of the week.
Any of the above keywords can be given the value :current which means to use the current value as
determined by a call to the operating system.
[Function]
extensions:format-universal-time dest universal-time
&key :timezone
:style :date-first
:print-seconds :print-meridian
:print-timezone :print-weekday
[Function]
extensions:format-decoded-time dest seconds minutes hours day month year
&key :timezone
:style :date-first
:print-seconds :print-meridian
:print-timezone :print-weekday
format-universal-time formats the time
specified by universal-time. format-decoded-time formats the time specified by
seconds, minutes, hours,
day, month, and
year. Dest is
any destination accepted by the format
function. The keyword arguments have the following meaning:
- :timezone
- is an integer specifying the hours west of
Greenwich. :timezone defaults to the current
time zone.
- :style
- specifies the style to use in formatting the
time. The legal values are:
- :short
- specifies to use a numeric date.
- :long
- specifies to format months and weekdays as
words instead of numbers.
- :abbreviated
- is similar to long except the words are
abbreviated.
- :government
- is similar to abbreviated, except the date is
of the form “day month year” instead of “month
day, year”.
- :date-first
- if non-nil (default) will
place the date first. Otherwise, the time is placed first.
- :print-seconds
- if non-nil (default) will
format the seconds as part of the time. Otherwise, the seconds will
be omitted.
- :print-meridian
- if non-nil (default) will
format “AM” or “PM” as part of the time.
Otherwise, the “AM” or “PM” will be
omitted.
- :print-timezone
- if non-nil (default) will
format the time zone as part of the time. Otherwise, the time zone
will be omitted.
- :print-weekday
- if non-nil (default) will
format the weekday as part of date. Otherwise, the weekday will be
omitted.
2.19 Random Number Generation
Common Lisp includes a random number
generator as a standard part of the language; however, the
implementation of the generator is not specified. Two random number
generators are available in CMUCL, depending on the version.
2.19.1 Original Generator
The default random number generator uses
a lagged Fibonacci generator given by
z[i] = z[i −
24] − z[i − 55] mod536870908
where z[i] is the i'th random number. This
generator produces small integer-valued numbers. For larger
integer, the small random integers are concatenated to produce
larger integers. For floating-point numbers, the bits from this
generator are used as the bits of the floating-point
significand.
2.19.2 New Generator
In some versions of CMUCL, the original
generator above has been replaced with a subtract-with-borrow
generator combined with a Weyl generator.1 The reason for the change was to
use a documented generator which has passed tests for
randomness.
The subtract-with-borrow generator is described by the following
equation
z[i] = z[i + 20]
− z[i + 5] − b
where z[i] is the i'th random number, which is
a double-float. All of the indices in this
equation are interpreted modulo 32. The quantity b is
carried over from the previous iteration and is either 0 or
double-float-epsilon. If z[i]
is positive, b is set to zero. Otherwise, b is set to
double-float-epsilon.
To increase the randomness of this generator, this generator is
combined with a Weyl generator defined by
x[i] = x[i −
1] − y mod1,
where y = 7097293079245107 × 2−53.
Thus, the resulting random number r[i] is
r[i] = (z[i]
− x[i]) mod1
This generator has been tested by Peter VanEynde using Marsaglia's
diehard test suite for random number generators; this generator
passes the test suite.
This generator is designed for generating floating-point random
numbers. To obtain integers, the bits from the significand of the
floating-point number are used as the bits of the integer. As many
floating-point numbers as needed are generated to obtain the
desired number of bits in the random integer.
For floating-point numbers, this generator can by significantly
faster than the original generator.
2.19.3 MT-19987 Generator
On all platforms, this is the preferred
generator as indicated by :rand-mt19987 being
in *features*. This is a Lisp implementation
of the MT-19987 generator of Makoto Matsumoto and T. Nishimura. We
refer the reader to their paper2 or to their website at http://www.math.keio.ac.jp/ matumoto/emt.html.
2.20 Lisp Threads
CMUCL supports Lisp threads for the x86
platform.
2.21 Lisp Library
The CMUCL project maintains a
collection of useful or interesting programs written by users of
our system. The library is in lib/contrib/. Two files there that users should
read are:
- CATALOG.TXT
- This file contains a page for each entry in the
library. It contains information such as the author, portability or
dependency issues, how to load the entry, etc.
- READ-ME.TXT
- This file describes the library's organization
and all the possible pieces of information an entry's catalog
description could contain.
Hemlock has a command Library Entry that
displays a list of the current library entries in an editor buffer.
There are mode specific commands that display catalog descriptions
and load entries. This is a simple and convenient way to browse the
library.
2.22 Generalized Function Names
[Macro]
ext:define-function-name-syntax name (var)
&body body
Define lists starting with the symbol
name as a new extended function name
syntax.
body is executed with var bound to an actual function name of that form, and
should return two values:
- A generalized boolean that is true if
var is a valid function name.
- A symbol that can be used as a block name in functions whose name is var. (For some sorts of function names it might make
sense to return nil for the block name, or
just return one value.)
Users should not define function names starting with a symbol that
CMUCL might be using internally. It is therefore advisable to only
define new function names starting with a symbol from a
user-defined package.
[Function]
ext:valid-function-name-p name
Returns two values:
- True if name is a
valid function name.
- A symbol that can be used as a block name in functions whose name is name. This can be nil for some
function names.
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.
2.23.3.1 slot-boundp Declaration
Example:
(defclass foo ()
(a b))
(defmethod bar ((x foo))
(declare (ext:slots (slot-boundp foo)))
(list (slot-value x 'a) (slot-value x 'b)))
The slot-boundp declaration in method
bar specifies that the slots a and b accessed through
parameter x in the scope of the declaration
are always bound, because parameter x is
specialized on class foo to which the
slot-boundp declaration applies. The
PCL-generated code for the slot-value forms
will thus not contain tests for the slots being bound or not. The
consequences are undefined should one of the accessed slots not be
bound.
2.23.3.2 inline Declaration
Example:
(defclass foo ()
(a b))
(defmethod bar ((x foo))
(declare (ext:slots (inline (foo a))))
(list (slot-value x 'a) (slot-value x 'b)))
The inline declaration in method bar tells PCL to use compile-time knowledge of slot
locations for accessing slot a of class
foo, in the scope of the declaration.
Class foo must be known at compile time for
this optimization to be possible. PCL prints a warning and uses
normal slot access If the class is not defined at compile time.
If a class is proclaimed to use inline slot
access before it is defined, the class is defined at compile time.
Example:
(declaim (ext:slots (inline (foo slot-a))))
(defclass foo () ...)
(defclass bar (foo) ...)
Class foo will be defined at compile time
because it is declared to use inline slot access; methods accessing
slot slot-a of foo will
use inline slot access if otherwise possible. Class bar will be defined at compile time because its
superclass foo is declared to use inline slot
access. PCL uses compile-time information from subclasses to warn
about situations where using inline slot access is not
possible.
Normal slot access will be used if PCL finds, at method compilation
time, that
- class foo has a
subclass in which slot a is at a different
location, or
- there exists a slot-value-using-class method for foo or a subclass of foo.
When the declaration is used to optimize calls to slot accessor
generic functions in methods, as opposed to slot-value or (setf slot-value),
the optimization is additionally not used if
- there exist, at compile time, applicable
methods on the reader/writer generic function that are not standard
accessor methods (for instance, there exist around-methods), or
- applicable reader/writer methods access
different slots in a class accessed inline, and one of its
subclasses.
The consequences are undefined if the compile-time environment is
not the same as the run-time environment in these respects, or if
the definition of class foo or any subclass
of foo is changed in an incompatible way,
that is, if slot locations change.
The effect of the inline optimization
combined with the slot-boundp optimization is
that CLOS slot access becomes as fast as structure slot access,
which is an order of magnitude faster than normal CLOS slot
access.
[Variable]
pcl::*optimize-inline-slot-access-p*
This variable controls if inline slot
access optimizations are performed. It is true by
default.
2.23.3.3 Automatic Method
Recompilation
Methods using inline slot access can be
automatically recompiled after class changes. Two declarations
control which methods are automatically recompiled.
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
If no specifier is given, auto-compilation is by default done/not
done for all methods of all generic functions using inline slot
access; current default is that it is not done. This global policy
can be overridden on a generic function and method basis. If
specifier is a generic function name, it
applies to all methods of that generic function.
Examples:
(declaim (ext:auto-compile foo))
(defmethod foo :around ((x bar)) ...)
The around-method foo will be automatically
recompiled because the declamation applies to all methods with name
foo.
(declaim (ext:auto-compile (foo (bar))))
(defmethod foo :around ((x bar)) ...)
(defmethod foo ((x bar)) ...)
The around-method will not be automatically recompiled, but the
primary method will.
(declaim (ext:auto-compile foo))
(declaim (ext:not-auto-compile (foo :around (bar)))
(defmethod foo :around ((x bar)) ...)
(defmethod foo ((x bar)) ...)
The around-method will not be automatically recompiled, because it
is explicitly declaimed not to be. The primary method will be
automatically recompiled because the first declamation applies to
it.
Auto-recompilation works by recording method bodies using inline
slot access. When PCL determines that a recompilation is necessary,
a defmethod form is constructed and
evaluated.
Auto-compilation can only be done for methods defined in a null
lexical environment. PCL prints a warning and doesn't record the
method body if a method using inline slot access is defined in a
non-null lexical environment. Instead of doing a recompilation on
itself, PCL will then print a warning that the method must be
recompiled manually when classes are changed.
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.
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)
[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 Differences from ANSI Common Lisp
This section describes some of the known differences between CMUCL
and ANSI Common Lisp. Some may be non-compliance issues; same may
be 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.25 Function Wrappers
Function
wrappers, fwrappers for short, are a facility for efficiently
encapsulating functions.
Functions in CMUCL are represented by kernel:fdefn objects. Each fdefn
object contains a reference to its function's actual code, which we
call the function's primary function.
A function wrapper replaces the primary function in the fdefn object with a function of its own, and records
the original function in an fwrapper object, a funcallable
instance. Thus, when the function is called, the fwrapper gets
called, which in turn might call the primary function, or a
previously installed fwrapper that was found in the fdefn object when the second fwrapper was
installed.
Example:
(use-package :fwrappers)
(define-fwrapper foo (x y)
(format t "x = ~s, y = ~s, user-data = ~s~%"
x y (fwrapper-user-data fwrapper))
(let ((value (call-next-function)))
(format t "value = ~s~%" value)
value))
(defun bar (x y)
(+ x y))
(fwrap 'bar #'foo :type 'foo :user-data 42)
(bar 1 2)
=>
x = 1, y = 2, user-data = 42
value = 3
3
Fwrappers are used in the implementation of trace and profile.
Please note that fdefinition always returns
the primary definition of a function; if a function is fwrapped,
fdefinition returns the primary function
stored in the innermost fwrapper object. Likewise, if a function is
fwrapped, (setf fdefinition) will set the
primary function in the innermost fwrapper.
[Macro]
fwrappers:define-fwrapper name lambda-list &bodybody
This macro is like defun, but defines a function named name that can be used as an fwrapper
definition.
In body, the symbol fwrapper is bound to the current fwrapper object.
The macro call-next-function can be used to
invoke the next fwrapper, or the primary function that is being
fwrapped. When called with no arguments, call-next-function invokes the next function with the
original arguments passed to the fwrapper, unless you modify one of
the parameters. When called with arguments, call-next-function invokes the next function with the
given arguments.
[Function]
fwrappers:fwrap function-name fwrapper &key type
user-data
This function wraps function function-name in an fwrapper fwrapper which was defined with define-fwrapper.
The value of type, if supplied, is used
as an identifying tag that can be used in various other
operations.
The value of user-data is stored as
user-supplied data in the fwrapper object that is created for the
function encapsulation. User-data is accessible in the body of
fwrappers defined with define-fwrapper as
(fwrapper-user-data fwrapper).
Value is the fwrapper object created.
[Function]
fwrappers:funwrap function-name &key type test
Remove fwrappers from the function named
function-name. If type is supplied, remove fwrappers whose type is
equal to type. If
test is supplied, remove fwrappers
satisfying test.
[Function]
fwrappers:find-fwrapper function-name &key type test
Find an fwrapper of function-name. If type is
supplied, find an fwrapper whose type is equal to type. If test is supplied, find an fwrapper satisfying
test.
[Function]
fwrappers:update-fwrapper fwrapper
Update the funcallable instance function
of the fwrapper object fwrapper from the
definition of its function that was defined with define-fwrapper. This can be used to update fwrappers
after changing a define-fwrapper.
[Function]
fwrappers:update-fwrappers function-name &key type
test
Update fwrappers of function-name; see update-fwrapper. If type is
supplied, update fwrappers whose type is equal to type. If test is supplied, update fwrappers satisfying
test.
[Function]
fwrappers:set-fwrappers function-name fwrappers
Set function-names's fwrappers to elements of the list
fwrappers, which is assumed to be ordered
from outermost to innermost. fwrappers
null means remove all fwrappers.
[Function]
fwrappers:list-fwrappers function-name
Return a list of all fwrappers of
function-name, ordered from outermost to
innermost.
[Function]
fwrappers:push-fwrapper fwrapper function-name
Prepend fwrapper fwrapper to the definition of function-name. Signal an error if function-name is an undefined
function.
[Function]
fwrappers:delete-fwrapper fwrapper function-name
Remove fwrapper fwrapper from the definition of function-name. Signal an error if function-name is an undefined
function.
[Macro]
fwrappers:do-fwrappers (var fdefn &optionalresult) &bodybody
Evaluate body
with var bound to consecutive fwrappers
of fdefn. Return result at the end. Note that fdefn must be an fdefn
object. You can use kernel:fdefn-or-lose, for
instance, to get the fdefn object from a
function name.
2.26 Dynamic-Extent Declarations
Note: As of the 19a release,
dynamic-extent is unfortunately
disabled by default. It is known to cause some issues with CLX and
Hemlock. The cause is not known, but causes random errors and
brokeness. Enable at your own risk. However, it is safe enough to
build all of CMUCL without problems.
On x86 and sparc, CMUCL can exploit dynamic-extent declarations by allocating objects on
the stack instead of the heap.
You can tell CMUCL to trust or not trust dynamic-extent declarations by setting the variable
*trust-dynamic-extent-declarations*.
[Variable]
ext:*trust-dynamic-extent-declarations*
If the value of *trust-dynamic-extent-declarations* is NIL, dynamic-extent declarations
are effectively ignored.
If the value of this variable is a function, the function is called
with four arguments to determine if a dynamic-extent declaration should be trusted. The
arguments are the safety, space, speed, and debug settings at the
point where the dynamic-extent declaration is
used. If the function returns true, the declaration is trusted,
otherwise it is not trusted.
In all other cases, dynamic-extent
declarations are trusted.
Please note that stack-allocation is inherently unsafe. If you make
a mistake, and a stack-allocated object or part of it escapes,
CMUCL is likely to crash, or format your hard disk.
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))
...))
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.27 Modular Arithmetic
This section is mostly taken, with
permission, from the documentation for SBCL.
Some numeric functions have a property: N
lower bits of the result depend only on N
lower bits of (all or some) arguments. If the compiler sees an
expression of form (logand exp mask), where
exp is a tree of such “good”
functions and mask is known to be of type
(unsigned-byte w), where w is a "good" width, all intermediate results will be
cut to w bits (but it is not done for
variables and constants!). This often results in an ability to use
simple machine instructions for the functions.
Consider an example.
(defun i (x y)
(declare (type (unsigned-byte 32) x y))
(ldb (byte 32 0) (logxor x (lognot y))))
The result of (lognot y) will be negative and
of type (signed-byte 33), so a naive
implementation on a 32-bit platform is unable to use 32-bit
arithmetic here. But modular arithmetic optimizer is able to do it:
because the result is cut down to 32 bits, the compiler will
replace logxor and lognot with versions cutting results to 32 bits, and
because terminals (here—expressions x
and y) are also of type (unsigned-byte 32), 32-bit machine arithmetic can be
used.
Currently “good” functions are +,
-, *; logand, logior, logxor, lognot and their
combinations; and ash with the positive
second argument. “Good” widths are 32 on HPPA, MIPS,
PPC, Sparc and X86 and 64 on Alpha. While it is possible to support
smaller widths as well, currently it is not implemented.
A more extensive description of modular arithmetic can be found in
the paper “Efficient Hardware Arithmetic in Common
Lisp” by Alexey Dejneka, and Christophe Rhodes, to be
published.
2.28 Extension to REQUIRE
The behavior of require when called with only one argument is
implementation-defined. In CMUCL, functions from the list
*module-provider-functions* are called in
order with the stringified module name as the argument. The first
function to return non-NIL is assumed to
have loaded the module.
By default the functions module-provide-cmucl-defmodule and module-provide- cmucl-library are on this list of
functions, in that order.
[Variable]
ext:*module-provider-functions*
This is a list of functions taking a
single argument. require calls each function
in turn with the stringified module name. The first function to
return non-NIL indicates that the module
has been loaded. The remaining functions, if any, are not
called.
To add new providers, push the new provider function onto the
beginning of this list.
[Macro]
ext:defmodule name &rest
files
Defines a module by registering the files
that need to be loaded when the module is required. If name is a symbol, its print name is used after
downcasing it.
[Function]
ext:module-provide-cmucl-defmodule module-name
This function is the module-provider for
modules registered by a ext:defmodule
form.
[Function]
ext:module-provide-cmucl-library module-name
This function is the module-provider for
CMUCL's libraries, including Gray streams, simple streams, CLX,
CLM, Hemlock, etc.
This function causes a file to be loaded whose name is formed by
merging the search-list “modules:” and the
concatenation of module-name with the suffix
“-LIBRARY”. Note that both the module-name and the
suffix are each, separately, converted from :case :common to :case
:local. This merged name will be probed with both a .lisp and .fasl
extensions, calling LOAD if it
exists.
- 1
- The generator described here is available if
the feature :new-random is available.
- 2
- “Mersenne Twister: A 623-Dimensionally
Equidistributed Uniform Pseudorandom Number Generator,” ACM
Trans. on Modeling and Computer Simulation, Vol. 8, No. 1, January
1998, pp.3–30