Previous Contents Next
Chapter 2 Design Choices and Extensions

Several design choices in Common Lisp are left to the individual implementation, and some essential parts of the programming environment are left undefined. This chapter discusses the most important design choices and extensions.

2.1 Data Types

2.1.1 Symbols

As in Common Lisp: The Language, all symbols and package names are printed in lower case, as a user is likely to type them. Internally, they are normally stored upper case only.

2.1.2 Integers

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.

2.1.3 Floats

CMUCL supports two floating point formats: single-float and double-float. These are implemented with IEEE single and double float arithmetic, respectively. short-float is a synonym for single-float, and long-float is a synonym for double-float. The initial value of *read-default-float-format* is single-float.

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

2.1.3.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.3.4), so users of the default configuration need not concern themselves with special values.

[Constant]
extensions:short-float-positive-infinity    
[Constant]
extensions:short-float-negative-infinity    
[Constant]
extensions:single-float-positive-infinity    
[Constant]
extensions:single-float-negative-infinity    
[Constant]
extensions:double-float-positive-infinity    
[Constant]
extensions:double-float-negative-infinity    
[Constant]
extensions:long-float-positive-infinity    
[Constant]
extensions:long-float-negative-infinity    

The values of these constants are the IEEE positive and negative infinity objects for each float format.

[Function]
extensions:float-infinity-p x    

This function returns true if x is an IEEE float infinity (of either sign.) x must be a float.

[Function]
extensions:float-nan-p x    

[Function]
extensions:float-trapping-nan-p x    

float-nan-p returns true if x is an IEEE NaN (Not A Number) object. float-trapping-nan-p returns true only if x is a trapping NaN. With either function, x must be a float.

2.1.3.2 Negative Zero

The IEEE float format provides for distinct positive and negative zeros. To test the sign on zero (or any other float), use the Common Lisp float-sign function. Negative zero prints as -0.0f0 or -0.0d0.

2.1.3.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.3.4.) The Common Lisp least-positive-format-float constants are denormalized.

[Function]
extensions:float-normalized-p x    

This function returns true if x is a denormalized float. x must be a float.

2.1.3.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.3.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.3.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.3.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.3.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. No currently supported machines have a fast mode.
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:

2.1.4 Characters

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

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 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, extensions, and pcl 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.
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 10.
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 lisp)
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 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).
2.4 The Editor

The ed function invokes the Hemlock editor which is described in Hemlock User's Manual and Hemlock Command Implementor's Manual. Most users at CMU prefer to use Hemlock's slave Common Lisp mechanism which provides an interactive buffer for the read-eval-print loop and editor commands for evaluating and compiling text from a buffer into the slave Common Lisp. Since the editor runs in the Common Lisp, using slaves keeps users from trashing their editor by developing in the same Common Lisp with Hemlock.

2.5 Garbage Collection

CMUCL uses a stop-and-copy garbage collector that compacts the items in dynamic space every time it runs. Most users cause the system to garbage collect (GC) frequently, long before space is exhausted. With 16 or 24 megabytes of memory, causing GC's more frequently on less garbage allows the system to GC without much (if any) paging.

The following functions invoke the garbage collector or control whether automatic garbage collection is in effect:

[Function]
extensions:gc    

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.

[Function]
extensions:gc-off    

This function inhibits automatic garbage collection. After calling it, the system will not GC unless you call ext:gc or ext:gc-on.

[Function]
extensions:gc-on    

This function reinstates automatic garbage collection. If the system would have GC'ed while automatic GC was inhibited, then this will call ext:gc.

2.5.1 GC Parameters

The following variables control the behavior of the garbage collector:

[Variable]
extensions:*bytes-consed-between-gcs*    

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

[Variable]
extensions:*gc-verbose*    

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

[Variable]
extensions:*gc-notify-before*    

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

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

[Variable]
extensions:*gc-notify-after*    

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

    [GC completed with 25,680 bytes retained and 2,096,808 bytes freed.]
    [GC will next occur when at least 2,025,680 bytes are in use.]
  
Note that a garbage collection will not happen at exactly the new threshold printed by the default ext:*gc-notify-after* function. The system periodically checks whether this threshold has been exceeded, and only then does a garbage collection.

[Variable]
extensions:*gc-inhibit-hook*    

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

[Variable]
extensions:*before-gc-hooks*    

[Variable]
extensions:*after-gc-hooks*    

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

2.5.2 Weak Pointers

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

[Function]
extensions:make-weak-pointer object    

[Function]
extensions:weak-pointer-value weak-pointer    

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

2.5.3 Finalization

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

[Function]
extensions:finalize object function    

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

[Function]
extensions:cancel-finalization object    

This function cancel any finalization request for object.

2.6 Describe

[Function]
describe object &optional stream    

The describe function prints useful information about object on stream, which defaults to *standard-output*. For any object, describe will print out the type. Then it prints other information based on the type of object. The types which are presently handled are:



hash-table
describe prints the number of entries currently in the hash table and the number of buckets currently allocated.
function
describe prints a list of the function's name (if any) and its formal parameters. If the name has function documentation, then it will be printed. If the function is compiled, then the file where it is defined will be printed as well.
fixnum
describe prints whether the integer is prime or not.
symbol
The symbol's value, properties, and documentation are printed. If the symbol has a function definition, then the function is described.
If there is anything interesting to be said about some component of the object, describe will invoke itself recursively to describe that object. The level of recursion is indicated by indenting output.
A number of switches can be used to control describe's behavior.

[Variable]
extensions:*describe-level*    

The maximum level of recursive description allowed. Initially two.

[Variable]
extensions:*describe-indentation*    

The number of spaces to indent for each level of recursive description, initially three.

[Variable]
extensions:*describe-print-level*    

[Variable]
extensions:*describe-print-length*    

The values of *print-level* and *print-length* during description. Initially two and five.

2.7 The Inspector

CMUCL has both a graphical inspector that uses the X Window System, and a simple terminal-based inspector.

[Function]
inspect &optional object    

inspect calls the inspector on the optional argument object. If object is unsupplied, inspect immediately returns nil. Otherwise, the behavior of inspect depends on whether Lisp is running under X. When inspect is eventually exited, it returns some selected Lisp object.

2.7.1 The Graphical Interface

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

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

[Function]
interface:lisp-control-panel    

This function creates a control panel for the Lisp process.

[Variable]
interface:*interface-style*    

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

2.7.2 The TTY Inspector

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

U
Move back to the enclosing object. As you descend into the components of an object, a stack of all the objects previously seen is kept. This command pops you up one level of this stack.
Q, E
Return the current object from inspect.
R
Recompute object display, and print again. Useful if the object may have changed.
D
Display again without recomputing.
H, ?
Show help message.
2.8 Load

[Function]
load filename &key :verbose :print :if-does-not-exist
:if-source-newer :contents    

As in standard Common Lisp, this function loads a file containing source or object code into the running Lisp. Several CMU extensions have been made to load to conveniently support a variety of program file organizations. filename may be a wildcard pathname such as *.lisp, in which case all matching files are loaded.

If filename has a pathname-type (or extension), then that exact file is loaded. If the file has no extension, then this tells load to use a heuristic to load the ``right'' file. The *load-source-types* and *load-object-types* variables below are used to determine the default source and object file types. If only the source or the object file exists (but not both), then that file is quietly loaded. Similarly, if both the source and object file exist, and the object file is newer than the source file, then the object file is loaded. The value of the if-source-newer argument is used to determine what action to take when both the source and object files exist, but the object file is out of date:

:load-object
The object file is loaded even though the source file is newer.
:load-source
The source file is loaded instead of the older object file.
:compile
The source file is compiled and then the new object file is loaded.
:query
The user is asked a yes or no question to determine whether the source or object file is loaded.
This argument defaults to the value of ext:*load-if-source-newer* (initially :load-object.)

The contents argument can be used to override the heuristic (based on the file extension) that normally determines whether to load the file as a source file or an object file. If non-null, this argument must be either :source or :binary, which forces loading in source and binary mode, respectively. You really shouldn't ever need to use this argument.

[Variable]
extensions:*load-source-types*    

[Variable]
extensions:*load-object-types*    

These variables are lists of possible pathname-type values for source and object files to be passed to load. These variables are only used when the file passed to load has no type; in this case, the possible source and object types are used to default the type in order to determine the names of the source and object files.

[Variable]
extensions:*load-if-source-newer*    

This variable determines the default value of the if-source-newer argument to load. Its initial value is :load-object.

2.9 The Reader

[Variable]
extensions:*ignore-extra-close-parentheses*    

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

2.10 Stream Extensions

[Function]
extensions: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.

2.11 Running Programs from Lisp

It is possible to run programs from Lisp by using the following function.

[Function]
extensions:run-program program args &key :env :wait :pty :input
:if-input-does-not-exist
:output :if-output-exists
:error :if-error-exists
:status-hook :before-execve    

run-program runs program in a child process. Program should be a pathname or string naming the program. Args should be a list of strings which this passes to program as normal Unix parameters. For no arguments, specify args as nil. The value returned is either a process structure or nil. The process interface follows the description of run-program. If run-program fails to fork the child process, it returns nil.

Except for sharing file descriptors as explained in keyword argument descriptions, run-program closes all file descriptors in the child process before running the program. When you are done using a process, call process-close to reclaim system resources. You only need to do this when you supply :stream for one of :input, :output, or :error, or you supply :pty non-nil. You can call process-close regardless of whether you must to reclaim resources without penalty if you feel safer.

run-program accepts the following keyword arguments:

:env
This is an a-list mapping keywords and simple-strings. The default is ext:*environment-list*. If :env is specified, run-program uses the value given and does not combine the environment passed to Lisp with the one specified.
:wait
If non-nil (the default), wait until the child process terminates. If nil, continue running Lisp while the child process runs.
:pty
This should be one of t, nil, or a stream. If specified non-nil, the subprocess executes under a Unix PTY. If specified as a stream, the system collects all output to this pty and writes it to this stream. If specified as t, the process-pty slot contains a stream from which you can read the program's output and to which you can write input for the program. The default is nil.
:input
This specifies how the program gets its input. If specified as a string, it is the name of a file that contains input for the child process. run-program opens the file as standard input. If specified as nil (the default), then standard input is the file /dev/null. If specified as t, the program uses the current standard input. This may cause some confusion if :wait is nil since two processes may use the terminal at the same time. If specified as :stream, then the process-input slot contains an output stream. Anything written to this stream goes to the program as input. :input may also be an input stream that already contains all the input for the process. In this case run-program reads all the input from this stream before returning, so this cannot be used to interact with the process.
:if-input-does-not-exist
This specifies what to do if the input file does not exist. The following values are valid: nil (the default) causes run-program to return nil without doing anything; :create creates the named file; and :error signals an error.
:output
This specifies what happens with the program's output. If specified as a pathname, it is the name of a file that contains output the program writes to its standard output. If specified as nil (the default), all output goes to /dev/null. If specified as t, the program writes to the Lisp process's standard output. This may cause confusion if :wait is nil since two processes may write to the terminal at the same time. If specified as :stream, then the process-output slot contains an input stream from which you can read the program's output.
:if-output-exists
This specifies what to do if the output file already exists. The following values are valid: nil causes run-program to return nil without doing anything; :error (the default) signals an error; :supersede overwrites the current file; and :append appends all output to the file.
:error
This is similar to :output, except the file becomes the program's standard error. Additionally, :error can be :output in which case the program's error output is routed to the same place specified for :output. If specified as :stream, the process-error contains a stream similar to the process-output slot when specifying the :output argument.
:if-error-exists
This specifies what to do if the error output file already exists. It accepts the same values as :if-output-exists.
:status-hook
This specifies a function to call whenever the process changes status. This is especially useful when specifying :wait as nil. The function takes the process as a required argument.
:before-execve
This specifies a function to run in the child process before it becomes the program to run. This is useful for actions such as authenticating the child process without modifying the parent Lisp process.
2.11.1 Process Accessors

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

[Function]
extensions:process-p thing    

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

[Function]
extensions:process-pid process    

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

[Function]
extensions:process-status process    

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

[Function]
extensions:process-exit-code process    

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

[Function]
extensions:process-core-dumped process    

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

[Function]
extensions:process-pty process    

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

[Function]
extensions:process-input process    

[Function]
extensions:process-output process    

[Function]
extensions:process-error process    

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

[Function]
extensions:process-status-hook process    

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

[Function]
extensions:process-plist process    

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

[Function]
extensions:process-wait process &optional check-for-stopped    

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

[Function]
extensions:process-kill process signal &optional whom    

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



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

[Function]
extensions:process-alive-p process    

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

[Function]
extensions:process-close process    

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

2.12 Saving a Core Image

A mechanism has been provided to save a running Lisp core image and to later restore it. This is convenient if you don't want to load several files into a Lisp when you first start it up. The main problem is the large size of each saved Lisp image, typically at least 20 megabytes.

[Function]
extensions:save-lisp file &key :purify :root-structures :init-function
:load-init-file :print-herald :site-init
:process-command-line    

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.
To resume a saved file, type:
lisp -core file

[Function]
extensions:purify file &key :root-structures :environment-name    

This function optimizes garbage collection by moving all currently live objects into non-collected storage. Once statically allocated, the objects can never be reclaimed, even if all pointers to them are dropped. This function should generally be called after a large system has been loaded and initialized.

:root-structures
is an optional list of objects which should be copied first to maximize locality. This should be a list of the main entry points for the resulting core image. The purification process tries to localize symbols, functions, etc., in the core image so that paging performance is improved. The default value is NIL which means that Lisp objects will still be localized but probably not as optimally as they could be.

defstruct structures defined with the (:pure t) option are moved into read-only storage, further reducing GC cost. List and vector slots of pure structures are also moved into read-only storage.

:environment-name
is gratuitous documentation for the compacted version of the current global environment (as seen in c::*info-environment*.) If nil is supplied, then environment compaction is inhibited.
2.13 Pathnames

In Common Lisp quite a few aspects of pathname semantics are left to the implementation.

2.13.1 Unix Pathnames

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

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

(parse "foo") ==> "foo", NIL, :NEWEST
(parse "foo.bar") ==> "foo", "bar", :NEWEST
(parse ".foo") ==> ".foo", NIL, :NEWEST
(parse ".foo.bar") ==> ".foo", "bar", :NEWEST
(parse "..") ==> ".", "", :NEWEST
(parse "foo.") ==> "foo", "", :NEWEST
(parse "foo.bar.1") ==> "foo", "bar", 1
(parse "foo.bar.baz") ==> "foo.bar", "baz", :NEWEST
The directory of pathnames beginning with a slash (or a search-list, see section 2.13.4) is starts :absolute, others start with :relative. The .. directory is parsed as :up; there is no namestring for :back:
(pathname-directory "/usr/foo/bar.baz") ==> (:ABSOLUTE "usr" "foo")
(pathname-directory "../foo/bar.baz") ==> (:RELATIVE :UP "foo")
2.13.2 Wildcard Pathnames

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

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

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

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

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

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

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

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.13.5 Predefined Search-Lists

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

default:
The current directory at startup.
home:
The user's home directory.
library:
The CMUCL lib/ directory (CMUCLLIB environment variable.)
path:
The Unix command path (PATH environment variable.)
target:
The root of the tree where CMUCL was compiled.
It can be useful to redefine these search-lists, for example, library: can be augmented to allow logical pathname translations to be located, and target: can be redefined to point to where CMUCL system sources are locally installed.

2.13.6 Search-List Operations

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

[Function]
extensions:search-list name    

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

[Function]
extensions:search-list-defined-p name    

[Function]
extensions:clear-search-list name    

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

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

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

2.13.7 Search List Example

The search list code: can be defined as follows:

(setf (ext:search-list "code:") '("/usr/lisp/code/"))
It is now possible to use code: as an abbreviation for the directory /usr/lisp/code/ in all file operations. For example, you can now specify code:eval.lisp to refer to the file /usr/lisp/code/eval.lisp.

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

(ext:search-list name)
Where name is the name of a search list as described above. For example, calling ext:search-list on code: as follows:
(ext:search-list "code:")
returns the list ("/usr/lisp/code/").

2.14 Filesystem Operations

CMUCL provides a number of extensions and optional features beyond those require by Common Lisp.

2.14.1 Wildcard Matching

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

[Function]
directory wildname &key :all :check-for-subdirs :truenamep
:follow-links    

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

:all
Include files beginning with dot such as .login, similar to ``ls -a''.
:check-for-subdirs
Test whether files are directories, similar to ``ls -F''.
:truenamep
Call truename on each file, which expands out all symbolic links. Note that this option can easily result in pathnames being returned which have a different directory from the one in the wildname argument.
:follow-links
Follow symbolic links when searching for matching directories.

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

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

2.14.2 File Name Completion

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

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

[Function]
extensions:ambiguous-files pathname &optional defaults    

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

2.14.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.15 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.16 Random Number Generation

Common Lisp includes a random number generator as a standard part of the language; however, the implementation of the generator is not specified. Two random number generators are available in CMUCL, depending on the version.

2.16.1 Original Generator

The default random number generator uses a lagged Fibonacci generator given by

z[i] = z[i - 24] - z[i - 55] mod 536870908

where z[i] is the i'th random number. This generator produces small integer-valued numbers. For larger integer, the small random integers are concatenated to produce larger integers. For floating-point numbers, the bits from this generator are used as the bits of the floating-point significand.

2.16.2 New Generator

In some versions of CMUCL, the original generator above has been replaced with a subtract-with-borrow generator combined with a Weyl generator.1 The reason for the change was to use a documented generator which has passed tests for randomness.

The subtract-with-borrow generator is described by the following equation

z[i] = z[i + 20] - z[i + 5] - b
where z[i] is the i'th random number, which is a double-float. All of the indices in this equation are interpreted modulo 32. The quantity b is carried over from the previous iteration and is either 0 or double-float-epsilon. If z[i] is positive, b is set to zero. Otherwise, b is set to double-float-epsilon.

To increase the randomness of this generator, this generator is combined with a Weyl generator defined by

x[i] = x[i - 1] - y mod 1,
where y = 7097293079245107 × 2-53. Thus, the resulting random number r[i] is
r[i] = (z[i] - x[i]) mod 1

This generator has been tested by Peter VanEynde using Marsaglia's diehard test suite for random number generators; this generator passes the test suite.

This generator is designed for generating floating-point random numbers. To obtain integers, the bits from the significand of the floating-point number are used as the bits of the integer. As many floating-point numbers as needed are generated to obtain the desired number of bits in the random integer.

For floating-point numbers, this generator can by significantly faster than the original generator.

2.17 Lisp Library

The CMUCL project maintains a collection of useful or interesting programs written by users of our system. The library is in lib/contrib/. Two files there that users should read are:

CATALOG.TXT
This file contains a page for each entry in the library. It contains information such as the author, portability or dependency issues, how to load the entry, etc.
READ-ME.TXT
This file describes the library's organization and all the possible pieces of information an entry's catalog description could contain.
Hemlock has a command Library Entry that displays a list of the current library entries in an editor buffer. There are mode specific commands that display catalog descriptions and load entries. This is a simple and convenient way to browse the library.
1
The generator described here is available if the feature :new-random is available.

Previous Contents Next