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.
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 three floating point formats:
single-float, double-float and
double-double-float. The first two are implemented with
IEEE single and double float arithmetic, respectively. The last is an
extension; see section 2.1.3 for more information.
short-float is a synonym for single-float, and
long-float is a synonym for double-float. The initial
value of *read-default-float-format* is single-float.
Both single-float and double-float are represented with
a pointer descriptor, so float operations can cause number consing.
Number consing is greatly reduced if programs are written to allow the
use of non-descriptor representations (see 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.
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 |
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
[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.
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.
CMUCL also has an extension to support double-double-float
type. This float format provides extended precision of about 31
decimal digits, with the same exponent range as double-float.
It is completely integrated into CMUCL, and can be used just like
any other floating-point object, including arrays, complex
double-double-float's, and special functions. With appropriate
declarations, no boxing is needed, just like single-float and
double-float.
The exponent marker for a double-double float number is ``W'', so
``1.234w0'' is a double-double float number.
Note that there are a few shortcomings with
double-double-float's:
-
There are no equivalents to most-positive-double-float,
double-float-positive-infinity, etc. This is because
these are not really well defined for double-double-float's.
- Underflow and overflow may be prematurely signaled. This is
due to how double-double-float's are implemented.
- Basic arithmetic operations are inlined, so the code size is
fairly large.
- double-double-float arithmetic is quite a bit slower
than double-float since there is no hardware support for
this type.
- The constant pi is still a double-float instead
of a double-double-float. Use ext:dd-pi if you
want a double-double-float value for p.
[float]
extensions:double-double-float
The double-double-float type. It is in the EXTENSIONS
package.
[Constant]
extensions:dd-pi
A double-double-float approximation to p.
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.5 |
Array Initialization |
|
If no :initial-value is specified, arrays are initialized to zero.
The hash-tables defined by Common Lisp have limited utility because they
are limited to testing their keys using the equality predicates
provided by (pre-CLOS) Common Lisp. CMUCL overcomes this limitation
by allowing its users to specify new hash table tests and hashing
methods. The hashing method must also be specified, since the
compiler is unable to determine a good hashing function for an
arbitrary equality (equivalence) predicate.
[Function]
extensions:define-hash-table-test hash-table-test-name test-function hash-function
The hash-table-test-name must be a symbol.
The test-function takes two objects and returns true
iff they are the same. The hash-function takes one object and
returns two values: the (positive fixnum) hash value and true if
the hashing depends on pointer values and will have to be redone
if the object moves.
To create a hash-table using this new ``test'' (really, a
test/hash-function pair), use
(make-hash-table :test
hash-table-test-name ...).
Note that it is the hash-table-test-name that will be
returned by the function hash-table-test, when applied to
a hash-table created using this function.
This function updates *hash-table-tests*, which is now
internal.
CMUCL also supports a number of weak hash tables. These weak
tables are created using the :weak-p argument to
make-hash-table. Normally, a reference to an object as either
the key or value of the hash-table will prevent that object from being
garbage-collected. However, in a weak table, if the only reference is
the hash-table, the object can be collected.
The possible values for :weak-p are listed below. An entry in
the table remains if the condition holds
-
:key
- The key is referenced elsewhere
- :value
- The value is referenced elsewhere
- :key-and-value
- Both the key and value are referenced elsewhere
- :key-or-value
- Either the key or value are referenced elsewhere
- T
- For backward compatibility, this means the same as :key.
If the condition does not hold, the object can be removed from the
hash table.
Weak hash tables can only be created if the test is eq or
eql. An error is signaled if this is not the case.
[Function]
make-hash-table &key :test :size :rehash-size :rehash-threshold :weak-p
Creates a hash-table with the specified properties.
| 2.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).
- xref
- The xref package exports the public
interface to the cross-referencing utility (see section 12).
| 2.4 |
Hierarchical Packages |
|
The Common Lisp package system, designed and standardized several years
ago, is not hierarchical. Since Common Lisp was standardized, other
languages, including Java and Perl, have evolved namespaces which are
hierarchical. This document describes a hierarchical package naming
scheme for Common Lisp. The scheme was proposed by Franz Inc and
implemented in their Allegro Common Lisp product; a
compatible implementation of the naming scheme is implemented in
CMUCL. This documentation is based on the Franz Inc. documentation,
and is included with permission.
The goals of hierarchical packages in Common Lisp are:
-
Reduce collisions with user-defined packages: it is a well-known
problem that package names used by the Lisp implementation and those
defined by users can easily conflict. The intent of hierarchical
packages is to reduce such conflicts to a minimum.
- Improve modularity: the current organization of packages in various
implementations has grown over the years and appears somewhat random.
Organizing future packages into a hierarchy will help make the
intention of the implementation more clear.
- Foster growth in Common Lisp programs, or modules, available to the CL
community: the Perl and Java communities are able to contribute code
to repositories, with minimal fear of collision, because of the
hierarchical nature of the name spaces used by the contributed code.
We want the Lisp community to benefit from shared modules in the same
way.
In a nutshell, a dot (.) is used to separate levels in package
names, and a leading dot signifies a relative package name. The choice
of dot follows Java. Perl, another language with hierarchical
packages, uses a colon (:) as a delimiter, but the colon is
already reserved in Common Lisp. Absolute package names require no
modifications to the underlying Common Lisp implementation. Relative
package names require only small and simple modifications.
| 2.4.2 |
Relative Package Names |
|
Relative package names are needed for the same reason as relative
pathnames, for brevity and to reduce the brittleness of absolute
names. A relative package name is one that begins with one or more
dots. A single dot means the current package, two dots mean the parent
of the current package, and so on.
Table 2.2 presents a number of examples,
assuming that the packages named foo, foo.bar,
mypack, mypack.foo, mypack.foo.bar,
mypack.foo.baz, mypack.bar, and mypack.bar.baz,
have all been created.
| 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 actually refers to the non-existent
package common-lisp-user.foo. Note that the purpose of
nicknames is to provide shorter names in place of the longer names
that are designed to be fully descriptive. The hope is that
hierarchical packages makes longer names unnecessary and thus makes
nicknames unnecessary.
- 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 have
: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.)
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.
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.
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.
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.
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.
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.
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.
[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.
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.
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.
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))
[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.)
[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.
CMUCL includes a partial implementation of Simple Streams, a
protocol that allows user-extensible streams1. 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. :output can also be a stream
in which case all output from the process is written to this
stream.
- :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.
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.
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 :executable
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.
- :executable
- If non-NIL, an executable image is created.
Normally, CMUCL consists of the C runtime along with a core
file image. When :executable is non-NIL, the core file is
incorporated into the C runtime, so one (large) executable is
created instead of a new separate core file.
This feature is only available on some platforms, as indicated by
having the feature :executable. Currently only x86 ports and
the solaris/sparc port have this feature.
To resume a saved file, type:
lisp -core file
However, if the :executable option was specified, you can just
use
file
since the executable contains the core file within the executable.
[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.
In Common Lisp quite a few aspects of pathname semantics are left to
the implementation.
Unix pathnames are always parsed with a unix-host object as the host and
nil as the device. The last two dots (.) in the namestring mark
the type and version, however if the first character is a dot, it is considered
part of the name. If the last character is a dot, then the pathname has the
empty-string as its type. The type defaults to nil and the version
defaults to :newest.
(defun parse (x)
(values (pathname-name x) (pathname-type x) (pathname-version x)))
(parse "foo") ==> "foo", NIL, NIL
(parse "foo.bar") ==> "foo", "bar", NIL
(parse ".foo") ==> ".foo", NIL, NIL
(parse ".foo.bar") ==> ".foo", "bar", NIL
(parse "..") ==> NIL, NIL, NIL
(parse "foo.") ==> "foo", "", NIL
(parse "foo.bar.~1~") ==> "foo", "bar", 1
(parse "foo.bar.baz") ==> "foo.bar", "baz", NIL
The directory of pathnames beginning with a slash (or a search-list,
see 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")
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"
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"))
Search lists are an extension to Common Lisp pathnames. They serve a function
somewhat similar to Common Lisp logical pathnames, but work more like Unix PATH
variables. Search lists are used for two purposes:
-
They provide a convenient shorthand for commonly used directory names,
and
- They allow the abstract (directory structure independent) specification
of file locations in program pathname constants (similar to logical pathnames.)
Each search list has an associated list of directories (represented as
pathnames with no name or type component.) The namestring for any relative
pathname may be prefixed with ``slist:'', indicating that the
pathname is relative to the search list slist (instead of to the current
working directory.) Once qualified with a search list, the pathname is no
longer considered to be relative.
When a search list qualified pathname is passed to a file-system operation such
as open, load or truename, each directory in the search
list is successively used as the root of the pathname until the file is
located. When a file is written to a search list directory, the file is always
written to the first directory in the list.
| 2.16.5 |
Predefined Search-Lists |
|
These search-lists are initialized from the Unix environment or when Lisp was
built:
-
default:
- The current directory at startup.
- home:
- The user's home directory.
- library:
- The CMUCL lib/ directory (CMUCLLIB environment
variable).
- path:
- The Unix command path (PATH environment variable).
- ld-library-path:
- The Unix LD_LIBRARY_PATH
environment variable.
- target:
- The root of the tree where CMUCL was compiled.
- modules:
- The list of directories where CMUCL's
modules can be found.
- ext-formats:
- The list of directories where CMUCL can
find the implementation of external formats.
It can be useful to redefine these search-lists, for example, library:
can be augmented to allow logical pathname translations to be located, and
target: can be redefined to point to where CMUCL system sources are
locally installed.
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.
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.
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.
[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.
On all platforms, the random number is MT-19937 generator as indicated by
:rand-mt19937 being in *features*. This is a Lisp
implementation of the MT-19937 generator of Makoto Matsumoto and
T. Nishimura. We refer the reader to their paper2 or to
their
website at
http://www.math.keio.ac.jp/ matsumoto/emt.html.
When CMUCL starts up, *random-state* is initialized by
reading 627 words from /dev/urandom, when available. If
/dev/urandom is not available, the universal time is used to
initialize *random-state*. The initialization is done as given
in Matsumoto's paper.
CMUCL supports Lisp threads for the x86 platform.
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.
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.
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.
Function wrappers, fwrappers for short, are a facility for efficiently
encapsulating functions3.
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 &body body
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 &optional
result) &body body
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.
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.
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.
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.
CMUCL support localization where messages can be presented in the
native language. This is done in the style of gettext which
marks strings that are to be translated and provides the lookup to
convert the string to the specified language.
All messages from CMUCL can be translated but as of this writing,
the only complete translation is a Pig Latin translation done by
machine. There are a few messages translated to Korean.
In general, translatable strings are marked as such by using the
functions intl:gettext and intl:ngettext or by using the
reader macros _ or _N. When loading or compiling, such
strings are recorded for translation. At runtime, such strings are
looked in and the translation is returned. Doc strings do not need to
be noted in any way; the are automatically noted for translation.
By default, recording of translatable strings is disabled. To enable
recording of strings, call intl:translation-enable.
[Function]
intl:translation-enable
Enable recording of translatable strings.
[Function]
intl:translation-disable
Disablle recording of translatable strings.
[Function]
intl:setlocale &optional locale
Sets the locale to the locale specified by locale. If
locale is not give or is nil, the locale is determined by
look at the environment variables LANGUAGE, LC_ALL,
LC_MESSAGES, or LANG. If none of these are set, the
locale is unchanged.
The default locale is ``C''.
[Function]
intl:textdomain domain
Set the default domain to the domain specified by domain.
Typically, this only needs to be done at the top of each source
file. This is used to gettext and ngettext to set the
domain for the message string.
[Macro]
intl:gettext string
Look up the specified string, string, in the current message
domain and return its translation.
[Function]
intl:dgettext domain string
Look up the specified string, string, in the message domain,
domain. The translation is returned.
When compiled, this also function also records the string so that an
appropriate message template file can be created. (See
intl::dump-pot-files.)
[Macro]
intl:ngettext singular plural n
Look up the singular or plural form of a message in the default
domain. The singular form is singular; the plural is
plural. The number of items is specified by n in case
the correct translation depends on the actual number of items.
[Function]
intl:dngettext domain singular plural n
Look up the singular or plural form of a message in the specified
domain, domain. The singular form is singular; the
plural is plural. The number of items is specified by n
in case the correct translation depends on the actual number of
items.
When compiled, this also function also records the singular and
plural forms so that an appropriate message template file can be
created. (See intl::dump-pot-files.)
[Function]
intl::dump-pot-files &key copyright
output-directory
Dumps the translatable strings recorded by dgettext and
dngettext. The message template file (pot file) is written
to a file in the directory specified by output-directory, and
the name of the file is the domain of the string.
If copyright is specified, this is placed in the output file
as the copyright message.
[Variable]
intl:*locale-directories*
This is a list of directory pathnames where the translations can be found.
[Function]
intl:install &optional (rt *readtable*)
Installs reader macros and comment reader into the specified
readtable as explained below. The readtable defaults to
*readtable*.
Two reader macros are also provided: _'' and _N''. The
first is equivalent to wrapping dgettext around the string.
The second returns the string, but also records the string. This is
needed when we want to record a docstring for translation or any other
string in a place where a macro or function call would be incorrect.
Also, the standard comment reader is extended to allow translator
comments to be saved and written to the messages template file so that
the translator may not need to look at the original source to
understand the string. Any comment line that begins with exactly
"TRANSLATORS: " is saved. This means each translator comment
must be preceded by this string to be saved; the translator comment
ends at the end of each line.
Here is a simple example of how to localize your code. Let the file
intl-ex.lisp contain:
(intl:textdomain "example")
(defun foo (x y)
"Cool function foo of x and y"
(let ((result (bar x y)))
;; TRANSLATORS: One line comment about bar.
(format t _"bar of ~A and ~A = ~A~%" x y result)
#| TRANSLATORS: Multiline comment about
how many Xs there are
|#
(format t (intl:ngettext "There is one X"
"There are many Xs"
x))
result))
The call to textdomain sets the default domain for all
translatable strings following the call.
Here is a sample session for creating a template file:
* (intl:install)
T
* (intl:translation-enable)
T
* (compile-file "intl-ex")
#P"/Volumes/share/cmucl/cvs/intl-ex.sse2f"
NIL
NIL
* (intl::dump-pot-files :output-directory "./")
Dumping 3 messages for domain "example"
NIL
*
When this file is compiled, all of the translatable strings are
recorded. This includes the docstring for foo, the string for
the first format, and the string marked by the call to
intl:ngettext.
A file named ``example.pot'' in the directory ``./'' is created.
The contents of this file are:
#@ example
# SOME DESCRIPTIVE TITLE
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION"
"Report-Msgid-Bugs-To: "
"PO-Revision-Date: YEAR-MO-DA HO:MI +ZONE"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>"
"Language-Team: LANGUAGE <LL@li.org>"
"MIME-Version: 1.0"
"Content-Type: text/plain; charset=UTF-8"
"Content-Transfer-Encoding: 8bit"
#. One line comment about bar.
#: intl-ex.lisp
msgid "bar of ~A and ~A = ~A~%"
msgstr ""
#. Multiline comment about
how many Xs there are
#: intl-ex.lisp
msgid "Cool function foo of x and y"
msgstr ""
#: intl-ex.lisp
msgid "There is one X"
msgid_plural "There are many Xs"
msgstr[0] ""
To finish the translation, a corresponding ``example.po'' file needs
to be created with the appropriate translations for the given
strings. This file must be placed in some directory that is included
in intl:*locale-directories*.
Suppose the translation is done for Korean. Then the user can set the
environment variables appropriately or call (intl:setlocale
"ko"). Note that the external format for the standard streams
needs to be set up appropriately too. It is up to the user to set
this correctly. Once this is all done, the output from the function
foo will now be in Korean instead of English as in the original
source file.
For further information, we refer the reader to documentation on
gettext at
http://www.gnu.org/software/gettext/manual/gettext.html.
CMUCL supports static arrays which are arrays that are not moved by
the garbage collector. To create such an array, use the
:allocation option to make-array with a value of
:malloc. These arrays appear as normal Lisp arrays, but are
actually allocated from the C heap (hence the :malloc).
Thus, the number and size of such arrays are limited by the available
C heap.
Also, only certain types of arrays can be allocated. The static array
cannot be adjustable and cannot be displaced to. The array must also
be a simple-array of one dimension. The element type is also
constrained to be one of the types in
Table 2.3.
| (unsigned-byte 8) |
| (unsigned-byte 16) |
| (unsigned-byte 32) |
| (signed-byte 8) |
| (signed-byte 16) |
| (signed-byte 32) |
| single-float |
| double-float |
| (complex single-float) |
| (complex double-float) |
Table 2.3: Allowed element types for static arrays
The arrays are properly handled by GC. GC will not move the arrays,
but they will be properly removed up if they become garbage.
- 1
- This
implementation was donated by Paul Foley
- 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
- 3
- This feature was independently
developed, but the interface is modelled after a similar feature in
Allegro. Some names, however, have been changed.