-@include package-locks-basic.texinfo
+@node Package Locks
+@comment node-name, next, previous, up
+@chapter Package Locks
+@cindex Packages, locked
-None of the following sections apply to SBCL built
-without package locks.
+None of the following sections apply to SBCL built without package
+locksing support.
-The interface described here is experimental: incompatible changes
-in future SBCL releases are possible, even expected.
+The interface described here is experimental: incompatible changes in
+future SBCL releases are possible, even expected: the concept of
+``implementation packages'' and the associated operators may be renamed;
+more operations (such as naming restarts or catch tags) may be added to
+the the list of operations violating package locks.
@menu
-* Package Locking Overview::
+* Package Lock Concepts::
+* Package Lock Dictionary::
+@end menu
+
+@node Package Lock Concepts
+@section Package Lock Concepts
+
+@menu
+* Package Lock Overview::
* Implementation Packages::
-* Package Locked Errors::
-* Package Locks in Compiled Code::
* Package Lock Violations::
-* Package Lock Dictionary::
+* Package Locks in Compiled Code::
+* Operations Violating Package Locks::
@end menu
-@node Package Locking Overview
-@section Package Locking Overview
-Package locks protect against unintentional modifications of a
-package: they provide similar protection to user packages as is
-mandated to @code{common-lisp} package by the ANSI specification. They
-are not, and should not be used as a security measure.
+@node Package Lock Overview
+@comment node-name, next, previous, up
+@subsection Package Locking Overview
+
+Package locks protect against unintentional modifications of a package:
+they provide similar protection to user packages as is mandated to
+@code{common-lisp} package by the ANSI specification. They are not, and
+should not be used as, a security measure.
Newly created packages are by default unlocked (see the @code{:lock}
option to @code{defpackage}).
but this is not currently done by default.
@node Implementation Packages
-@section Implementation Packages
+@subsection Implementation Packages
+@vindex *package*
+@findex defpackage
Each package has a list of associated implementation packages. A
locked package, and the symbols whose home package it is, can be
@code{sb-ext:remove-implementation-package} each package is its own
(only) implementation package.
-@node Package Locked Errors
-@section Package Locked Errors
+@node Package Lock Violations
+@subsection Package Lock Violations
+@tindex sb-ext:package-lock-violation
+@tindex sb-ext:package-locked-error
+@tindex sb-ext:symbol-package-locked-error
+@tindex package-lock-violation
+@tindex package-locked-error
+@tindex symbol-package-locked-error
+@tindex package-error
If an operation violates a package lock, a continuable error that is
of a subtype of @code{sb-ext:package-lock-violation} (subtype of
errors of type @code{sb-ext:symbol-package-locked-error}.
@node Package Locks in Compiled Code
-@section Package Locks in Compiled Code
-
-@subsection Lexical bindings and declarations
+@subsection Package Locks in Compiled Code
+
+@subsubsection Lexical bindings and declarations
+@findex let
+@findex let*
+@findex flet
+@findex labels
+@findex macrolet
+@findex symbol-macrolet
+@findex declare
+@cindex Declarations
+@findex sb-ext:disable-package-locks
+@findex sb-ext:enable-package-locks
+@findex disable-package-locks
+@findex enable-package-locks
Compiling lexical binding constructs or lexical declarations that
-violate package locks package cause a compile-time package-lock
-violation. A complete listing of operators affect by this is:
-@code{let}, @code{let*}, @code{flet}, @code{labels}, @code{macrolet},
-and @code{symbol-macrolet}, @code{declare}.
+violate package locks causes a compile-time package-lock violation. A
+complete listing of operators affect by this is: @code{let},
+@code{let*}, @code{flet}, @code{labels}, @code{macrolet}, and
+@code{symbol-macrolet}, @code{declare}.
Package locks affecting both lexical bindings and declarations can be
disabled at compile-time with @code{sb-ext:disable-package-locks}
,@@body)))
@end lisp
-@subsection Interned symbols
+@subsubsection Interned symbols
-If compiled code contains interned symbols, then loading that code
+If file-compiled code contains interned symbols, then loading that code
into an image without the said symbols will not cause a package lock
-violation even if the packages in question are locked.
+violation, even if the packages in question are locked.
-@subsection Other limitations on compiled code
+@subsubsection Other limitations on compiled code
With the exception of the aforementioned contructs, and interned
symbols, behaviour is unspecified if package locks affecting compiled
spurious package-lock-violations at runtime even if the packages are
unlocked.
-In practise all this means that package-locks have a neglible
+In practice all this means that package-locks have a neglible
performance penalty in compiled code as long as they are not violated.
-@node Package Lock Violations
-@section Package Lock Violations
+@node Operations Violating Package Locks
+@subsection Operations Violating Package Locks
-@heading Operations on Packages
+@subsubsection Operations on Packages
-Following actions cause a package lock violation if the package
+The following actions cause a package lock violation if the package
operated on is locked, and @code{*package*} is not an implementation
package of that package, and the action would cause a change in the
-state of the package (eg. exporting already external symbols is
-allowed). Package lock violations caused by these operations signal
-errors of type @code{sb-ext:package-locked-error}.
+state of the package (so e.g. exporting already external symbols is
+never a violation). Package lock violations caused by these operations
+signal errors of type @code{sb-ext:package-locked-error}.
@enumerate
@item
@end enumerate
-@heading Operations on Symbols
+@subsubsection Operations on Symbols
Following actions cause a package lock violation if the home package
of the symbol operated on is locked, and @code{*package*} is not an
Example:
@lisp
-;; Packages FOO and BAR are locked.
-;;
-;; Two lexically apparent violated packages: exactly two
-;; package-locked-errors will be signalled.
+;;; Packages FOO and BAR are locked.
+;;;
+;;; Two lexically apparent violated packages: exactly two
+;;; package-locked-errors will be signalled.
(defclass foo:point ()
((x :accessor bar:x)
Syntax: @code{(sb-ext:enable-package-locks symbol*)}
-Re-enables package locks affecting the named symbols during
-compilation in the lexical scope of the declaration. Enabling locks
-that were not first disabled with @code{sb-ext:disable-package-locks}
-declararion, or enabling locks that are already enabled has no effect.
+Re-enables package locks affecting the named symbols during compilation
+in the lexical scope of the declaration. Enabling locks that were not
+first disabled with @code{sb-ext:disable-package-locks} declararion, or
+enabling locks that are already enabled has no effect.
@end deftp
@include condition-sb-ext-package-lock-violation.texinfo
@include condition-sb-ext-package-locked-error.texinfo
@include condition-sb-ext-symbol-package-locked-error.texinfo
-@defun sb-ext:package-locked-error-symbol @var{symbol-package-locked-error}
+@defun sb-ext:package-locked-error-symbol symbol-package-locked-error
Returns the symbol that caused the @code{symbol-package-locked-error}
condition.
@include macro-sb-ext-without-package-locks.texinfo
@include macro-sb-ext-with-unlocked-packages.texinfo
-@defmac defpackage name [[@var{option}]]* @result{} package
+@defmac defpackage name [[option]]* @result{} package
Options are extended to include the following: