Skip to content
Snippets Groups Projects
Commit 4978f6a7 authored by emarsden's avatar emarsden
Browse files

- add documentation for package locks to the User's Manual

  - correct some information about implementation packages (CL !=
    LISP), reference CLOS-MOP package

  - "new, improved" title page
parent 1a960279
No related branches found
No related tags found
No related merge requests found
......@@ -112,7 +112,8 @@
\newenvironment{lisp}
{\@open{BLOCKQUOTE}{CLASS=lisp} \begin{alltt}}
{\end{alltt}\@close{BLOCKQUOTE}}
\newcommand{\cmucl}{CMUCL}
% there are no page numbers in HTML, so we need to override certain
% cross-referencing macros
......
......@@ -29,7 +29,6 @@
%% Delete "[a4paper]" if you don't want this formatted for A4 paper.
\documentclass[a4paper]{report}
%\usepackage[T1]{fontenc}
\usepackage{xspace}
\usepackage{alltt}
\usepackage{index}
......@@ -46,26 +45,50 @@
\newcommand{\keywords}{lisp, Common Lisp, manual, compiler, programming
language implementation, programming environment}
\date{CMUCL snapshot from \today{}}
% \date{March 18, 2003 \\ Release 18e}
\begin{document}
\date{\bigskip % \today %% Don't usually want that!
% Use the release date, whatever that might be
March 18, 2003 \\
Release 18e
\\
\vspace{0.5in} \textbf{Abstract} \medskip
\begin{quote}
CMUCL is a free, high-performance implementation of the Common Lisp
programming language, which runs on most major Unix platforms. It
mainly conforms to the ANSI Common Lisp Standard. CMUCL features a
sophisticated native-code compiler, a foreign function interface, a
graphical source-level debugger, an interface to the X11 Window
System, and an Emacs-like editor.
\end{quote}
\begin{titlepage}
\makeatletter
\vspace{60pt}
\begin{center}
\rule{\linewidth}{0.7mm}
\vspace{3em}
{\Huge \@title \par}
\vspace{4em}
{\large
\begin{tabular}[t]{c}
\@author
\end{tabular}\par}
\vspace{2em}
{\large \@date \par}
\vspace{2em}
\rule{\linewidth}{0.7mm}
\end{center}
\vfill
{\bf Keywords}: \keywords}
\begin{quotation}
\cmucl{} is a free, high-performance implementation of the Common Lisp
programming language, which runs on most major Unix platforms. It
mainly conforms to the ANSI Common Lisp Standard. \cmucl{} features a
sophisticated native-code compiler, a foreign function interface, a
graphical source-level debugger, an interface to the X11 Window
System, and an Emacs-like editor.
\medskip \textbf{Keywords}: \keywords
\end{quotation}
\vspace{5cm}
This manual is based on CMU Technical Report CMU-CS-92-161, edited by
Robert A. MacLachlan, dated July 1992.
\thispagestyle{empty}
\makeatother
\end{titlepage}
\ifpdf
\pdfinfo{
......@@ -79,7 +102,7 @@ language implementation, programming environment}
bookmarksopenlevel=2}
\fi
\maketitle
% \maketitle
\pagestyle{headings}
\pagenumbering{roman}
......
......@@ -457,14 +457,13 @@ your own signal handlers.
\section{Implementation-specific Packages}
When \cmucl{} is first started up, the default package is the
\code{common-lisp-user} package. The \code{common-lisp-user} package
uses the \code{common-lisp}, \code{extensions}, and \code{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.
\code{common-lisp-user} package. The \code{common-lisp-user} package
uses the \code{common-lisp} and \code{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.
\begin{Lentry}
\item[\code{alien}, \code{c-call}] Export the features of the Alien
......@@ -473,7 +472,11 @@ name.
\item[\code{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 \cltltwo.
CLOS chapter of \cltltwo{}.
\item[\code{clos-mop (mop)}] This package contains an implementation
of the CLOS Metaobject Protocol, as per the book \textit{The Art of
the Metaobject Protocol}.
\item[\code{debug}] The \code{debug} package contains the command-line
oriented debugger. It exports utility various functions and
......@@ -503,10 +506,10 @@ name.
\item[\code{profile}] The \code{profile} package exports a simple
run-time profiling facility (\pxlref{profiling}).
\item[\code{common-lisp (cl lisp)}] The \code{common-lisp} package
\item[\code{common-lisp (cl)}] The \code{common-lisp} package
exports all the symbols defined by \cltl{} and only those symbols.
Strictly portable Lisp code will depend only on the symbols exported
from the \code{lisp} package.
from the \code{common-lisp} package.
\item[\code{unix}] This package exports system call
interfaces to Unix (\pxlref{unix-interface}).
......@@ -531,6 +534,8 @@ name.
\input{hierarchical-packages}
\input{package-locks}
\section{The Editor}
......
\section{Package locks}
\cindex{package locks}
\cmucl{} provides two types of package locks, as an extension to the
ANSI Common Lisp standard. The package-lock protects a package from
changes in its structure (the set of exported symbols, its use list,
etc). The package-definition-lock protects the symbols in the package
from being redefined due to the execution of a \code{defun},
\code{defmacro}, \code{defstruct}, \code{deftype} or \code{defclass}
form.
\subsection{Rationale}
Package locks are an aid to program development, by helping to detect
inadvertent name collisions and function redefinitions. They are
consistent with the principle that a package ``belongs to'' its
implementor, and that noone other than the package's developer should
be making or modifying definitions on symbols in that package. Package
locks are compatible with the ANSI Common Lisp standard, which states
that the consequences of redefining functions in the
\code{COMMON-LISP} package are undefined.
Violation of a package lock leads to a continuable error of type
\code{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 \code{COMMON-LISP}
package, or to redefine a function in one of \cmucl{}'s
implementation-defined packages:
\begin{verbatim}
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.
\end{verbatim}
The following transcript illustrates the behaviour seen when an
attempt to modify the structure of a package is made:
\begin{verbatim}
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.
\end{verbatim}
The \code{COMMON-LISP} package and the \cmucl{}-specific
implementation packages are locked on startup. Users can lock their
own packages by using the \code{ext:package-lock} and
\code{ext:package-definition-lock} accessors.
\subsection{Disabling package locks}
A package's locks can be enabled or disabled by using the
\code{ext:package-lock} and \code{ext:package-definition-lock}
accessors, as follows:
\begin{lisp}
(setf (ext:package-lock (find-package "UNIX")) nil)
(setf (ext:package-definition-lock (find-package "UNIX")) nil)
\end{lisp}
\begin{defun}{ext:}{package-lock}{\var{package}}
This function is an accessor for a package's structural lock, which
protects it against modifications to its list of exported symbols.
\end{defun}
\begin{defun}{ext:}{package-definition-lock}{\var{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 \code{defstruct}, \code{defclass} or
\code{deftype} will be trapped.
\end{defun}
\begin{defmac}{ext:}{without-package-locks}{\args{\amprest{} \var{body}}}
This macro can be used to execute forms with all package locks (both
structure and definition locks) disabled.
\end{defmac}
\begin{defun}{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.
\end{defun}
% EOF
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment