Clasp Manual

Clasp conforms with the requirements of ANSI INCITS 226-1994 (R2004) with some exceptions, listed below in the "Lisp" section. Any deviation from the standard not listed there is a bug, and should be reported (see "Contributing").

At present, the developers do not make Clasp binaries available. Clasp is open source, and available on-line at https://github.com/clasp-developers/clasp.

See Building.

Check the community page for instructions on contributing to Clasp.

Discussions of Clasp development are mostly carried out on Freenode's #clasp channel.

Clasp is the project of Dr. Christian Schafmeister. Additional contributions have been made by Tarn W. Burton, Karsten Poeck, Alex Wood, and many other contributors as seen in the Git history.

Clasp's source code is derived substantially from that of Embeddable Common Lisp. Code from SBCL and SICL has been incorporated as well. Most notably, the compiler is SICL's Cleavir compiler with some minor customizations.

Clasp expands compiler macros essentially unconditionally. That is, provided the operator is not declared notinline, the compiler will attempt to expand compiler macros. If compiler macroexpansion signals, this signal will be recorded and reported by the compiler. If compiler macroexpansion errors out, the compiler will abandon expansion and use the unexpanded form, while noting the error for display.

ext:with-current-source-form is a useful macro to allow error messages from macroexpanders and compiler-macro-expanders to have more specific source information. See its docstring for more information.

typep calls can be efficiently compiled only if the second argument, the type specifier, is constant. Clasp's compiler will process the type specifier and generate code to check for objects of that type directly, avoiding the usual runtime cost of interpreting the type.

Types defined by deftype use a "type expander" function analogous to a macro expander function. A type expander is a function of two arguments, a type specifier and an environment. When called on an appropriate specifier and environment, it computes and returns another type specifier. Type expanders are accessible through the ext:type-expander accessor.

defsetf, define-setf-expander etc. define a "setf expander" function analogous to a macro expander function. A setf expander is a function of two arguments, a place and an environment. When called an appropriate place and environment, the expander computes and returns the values used by setf. Setf expanders are accessible through the ext:setf-expander accessor.

loop supports iteration over general sequences (see below) through a for-as-sequence subclause. This is identical to the subclause in SBCL. The syntax is being {each | the} {element | elements} {of | in}. For example, (loop for x being each element in '(1 2 3) do (print x)).

CLOS, as part of Common Lisp, is fully supported.

In addition to cl:restart-name, Clasp provides some readers to introspect about restarts, for advanced users (e.g. writing your own debugger, or the Dissect library): ext:restart-function returns the function called by cl:invoke-restart, and ext:report-function, ext:interactive-function, and ext:interactive-function return the corresponding arguments in cl:restart-bind. These will always be appropriate functions, so for example ext:report-function will always return a function of one stream argument, but if no :report-function was provided it will report the restart in Clasp's default way. The identities of these returned functions cannot be relied on, i.e. they may not be identical to those provided to cl:restart-bind.

There is also ext:restart-associated-conditions, which returns a list of conditions associated (by cl:with-condition-restarts) with the restart in the current dynamic environment.

Clasp supports package-local nicknames, through an interface based on that of SBCL's. A package-local nickname is a nickname for a package that is only active when some other package is in place as *package*. For example, if the package "FOO" has "B" as a package-local nickname for package "BAR", then while *package* is the foo package, the prefix "B:" will be read as if it was "BAR:".

Local nicknames may be specified in defpackage through the (:local-nicknames (nickname package-name)*) extended options. nickname must be a string designator and package-name a package designator - both are unevaluated. The functions ext:package-local-nicknames, ext:add-package-local-nickname, ext:remove-package-local-nickname, and ext:package-locally-nicknamed-by-list can be used for a more programmatic interface.

There are two types of floats, single-float and double-float. short-float is synonymous with the former and long-float is synonymous with the latter, per the standard's requirements. single-float is in the IEEE754 binary32 (single) format, and double-float in binary64 (double) format. The representation of a float as bits can be interconverted with a float using the functions ext:single-float-to-bits, bits-to-single-float, double-float-to-bits, and bits-to-double-float. These functions take or return nonnegative integers; for example (logbitp 31 (ext:single-floats-to-bit float)) returns whether the sign bit is set.

Clasp supports Unicode by default. code-char and char-code work with Unicode codepoints. Unicode character names are also supported, e.g. (princ #\GREEK_SMALL_LETTER_LAMDA) -> λ. =(defun λ(n)(* 2 n)) (λ 32) -> 64=is also possible.

Type character includes all characters in Unicode. Type base-char includes only single byte characters, i.e. Basic Latin and Latin-1 Supplement.

In Clasp, arrays with no fill-pointer, displacement, or express adjustability are simple (as in simple-array), and arrays that have any of these are not. Additionally, Clasp implements multidimensional arrays - even ones that are simple in this sense - as if they were displaced to an underlying one dimensional array. As such, it is most efficient to work with one-dimensional simple arrays directly.

make-hash-table supports additional keyword arguments.

:weakness can be used to indicate that the garbage collection may collect individual hash table entries even when the hash table itself is live, in certain circumstances. At present, only weak-key hash tables are supported: when the weakness argument is :key, the hash table's reference to the key of a table entry is weak, and if there are no non-weak references to a key, it is collectable. See the "Garbage Collection" section below for more information on weak references. If the weakness parameter is passed as nil, or not passed, the hash table does not contain weak references.

:thread-safe can be used to make hash table access safe across multiple threads. If a thread-safe argument is not passed, or nil is passed, the hash table cannot safely be written to or read from multiple threads simultaneously (see "Memory Model", below, for a brief explanation of terminology). If the thread-safe argument is true, the implementation will ensure that accesses can be carried out from multiple threads simultaneously safely. This does impose a small performance penalty, which is why it is not the default.

If a :test other than a standard equality predicate is passed, :hash-function must be specified as well. The hash function should be a designator for a function of one argument that is analogous to sxhash, i.e. (funcall test x y) implies ( (funcall hash-function x) (funcall hash-function y))= and so on. This will create a "custom" hash table that can be used with the standard hash table functions like gethash, with the exception that at the moment, attempting to dump a custom hash table has undefined consequences.

ext:rmdir deletes a directory. EXT:RMTREE deletes an entire directory tree.

When format's control string argument is constant, the compiler will process it early, so that the runtime doesn't have to. This improves runtime speed but increases code size.

A process is a Lisp object representing a distinct thread of execution. Each process evaluates a call to a Lisp function, and exits when that call would finally return values. Processes have names for debugging purposes. Processes are "nascent" or "not yet started" if they haven't yet begun evaluating, "active" if they have begun evaluating, "suspended" if that evaluation has been paused by process-suspend, and "exited" if they have finished evaluation (normally or by aborting).

Processes have type process. make-process creates a new process but does not start it. process-start enables a process, and process-run-function both creates and enables a process. The name of a process can be retrieved with process-name. process-active-p can be used to query whether a process is active. process-suspend, process-resume, interrupt-process, and process-kill interfere with a process's evaluation. process-join waits until a process until it completes, and then returns the values its function returned, or signals an error of type process-join-error if the process ended abnormally. Within a process, exit-process can be used to end the process's evaluation immediately, and abort-process to do so abnormally; in either case the dynamic environment is properly unwound. all-processes gets a list of all enabled processes. The variable *current-process* is bound in any process to that process. Consult the docstrings of these functions for more information.

Bindings of special variables (by let, progv, lambda lists, etc.) are thread-local. That is, executing a binding form for a variable will not affect that variable's value in other threads. The global value - from symbol-value - is, in contrast, shared between threads.

A mutex (short for "MUTual EXclusion"), or lock, can be used to control access to a shared resource by multiple processes.

Mutexes have type mutex. A mutex is created with make-lock, or make-recursive-mutex for a recursive mutex. get-lock and giveup-lock obtain and release exclusion on a mutex, respectively. mutex-name retrieves any name of a mutex given at creation.

Not yet documented.

Not yet documented.

Clasp does not have a formal memory model. Here is a sketch of one: Two accesses of a place are concurrent if they take place in different threads and are not excluded from running simultaneously by locks. Two concurrent accesses conflict if at least one is a write. If a conflicting access is not atomic the program has undefined behavior (e.g. tearing).

Some accesses are atomic but unordered, meaning that there is not necessarily a modification order to the place that is observed by all threads, e.g. one thread may see writes occur in a different order from another thread. Some accesses are sequentially consistent, meaning that there is such a globally observable modification order, and furthermore that all sequentially consistent accesses have a globally observable order.

Places may be complex, indeed completely custom. Clasp defines atomicity of some simple places; other places, and more complex modification operations, should hopefully be understandable from those. For example, to setf the second of a list, one cdr must be read before a car is written, and each of these individual accesses is atomic while the overall access is not.

In general Clasp tries to guarantee unordered atomicity, but does not always succeed, and in some cases it's probably not possible.

Note that in this context "atomic" does not necessarily mean "lock-free", although Clasp attempts to make atomic operations proceed without locks.

Places that can be accessed unorderedly are: car, cdr, symbol-value, symbol-plist, symbol-function=/=fdefinition, compiler-macro-function, ext:setf-expander, ext:type-expander. Access to the elements of simple one-dimensional arrays should be unordered, except for integer element types smaller than (unsigned-byte 8). Access to standard-object and structure-object slots (of :instance or :class allocation) should also be unordered.

Access can be guaranteed atomic by using the atomic macro. That is, (atomic place) is a place that can be accessed atomically, or else an error will be signaled. Clasp defines car, cdr, first, rest, symbol-value, special variables, symbol-plist, standard-instance-access, slot-value, clos:slot-value-using-class, and svref as atomically accessible, as well as the place or macro places that expand to these places. Additional atomically accessible places can be defined with the define-atomic-expansion macro. See its documentation string for more information. Additionally, documentation on atomic access may be available with kind atomic; e.g. try (documentation 'symbol-value 'mp:atomic).

The mp:cas macro can be used to execute an atomic compare-and-swap of atomically accessible places. See its docstring for more information. cas is used to define higher order atomic read-modify-write operations provided by Clasp: atomic-update, atomic-incf, atomic-decf, atomic-push, atomic-pop, and atomic-pushnew. The first is a general operator analogous to what define-modify-macro operators do, while the others are analogous to their standard versions. -explicit variants can be used to explicitly specify the order of the operation.

The mp:fence function can be used to establish memory fences of a specified order.

Handlers for standard POSIX signals can be defined in Clasp using the ext:enable-interrupt function, which expects a keyword to identify the type of signal (e.g. :sigpipe for SIGPIPE). If a Lisp function is used as the handler, it must be a function of one argument, the signal number. ext:enable-interrupt, or ext:ignore-interrupt and ext:default-interrupt, can be used to set the handler to the ignore-signal handler or the default handler respectively, analogous to SIG_IGN and SIG_DFL. The current handler function, if there is one, can be retrieved with ext:get-signal-handler.

ext:stat and ext:fstat wrap the corresponding posix-interfaces. Use ext:file-stream-file-descriptor to get the file-descriptor for a stream. The environment can be accessed with EXT:SETENV=and =EXT:GETENV Working directories can be accessed with EXT:GETCWD=and =EXT:CHDIR.