@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
-locksing support.
+locking support.
The interface described here is experimental: incompatible changes in
-future SBCL releases are possible, even expected: most notably the
-consept of implementation packages and the associated operators may be
-renamed.
+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 list of operations violating package locks.
@menu
-* Package Lock Concepts::
-* Package Lock Dictionary::
+* Package Lock Concepts::
+* Package Lock Dictionary::
@end menu
@node Package Lock Concepts
@section Package Lock Concepts
@menu
-* Package Lock Overview::
+* Package Lock Overview::
* Implementation Packages::
-* Package Lock Violations::
-* Package Locks in Compiled Code::
-* Operations Violating Package Locks::
+* Package Lock Violations::
+* Package Locks in Compiled Code::
+* Operations Violating Package Locks::
@end menu
@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.
+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}).
@node Implementation Packages
@subsection Implementation Packages
+@vindex @cl{@earmuffs{package}}
+@findex @cl{defpackage}
Each package has a list of associated implementation packages. A
locked package, and the symbols whose home package it is, can be
@node Package Lock Violations
@subsection Package Lock Violations
-
-If an operation violates a package lock, a continuable error that is
-of a subtype of @code{sb-ext:package-lock-violation} (subtype of
-@code{package-error}) is signalled when the operation is attempted.
-
-Additional restarts may be established for continuable package lock
-violations for interactive use.
-
-The actual type of the error depends on circumstances that caused the
-violation: operations on packages signal errors of type
-@code{sb-ext:package-locked-error}, and operations on symbols signal
-errors of type @code{sb-ext:symbol-package-locked-error}.
-
-@node Package Locks in Compiled Code
-@subsection Package Locks in Compiled Code
-
-@subsubsection Lexical bindings and declarations
-
-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}.
+@tindex @sbext{package-lock-violation}
+@tindex @sbext{package-locked-error}
+@tindex @sbext{symbol-package-locked-error}
+@tindex @cl{package-error}
+
+@subsubsection Lexical Bindings and Declarations
+@findex @cl{let}
+@findex @cl{let*}
+@findex @cl{flet}
+@findex @cl{labels}
+@findex @cl{macrolet}
+@findex @cl{symbol-macrolet}
+@findex @cl{declare}
+@cindex Declarations
+@findex @sbext{disable-package-locks}
+@findex @sbext{enable-package-locks}
+
+Lexical bindings or declarations that violate package locks cause a
+compile-time warning, and a runtime @code{program-error} when the form
+that violates package locks would be executed.
+
+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}
-declaration, and re-enabled with @code{sb-ext:enable-package-locks}
-declaration. Constructs compiled with package locks thusly disabled
-are guaranteed not to signal package lock violation errors at runtime.
+disabled locally with @code{sb-ext:disable-package-locks} declaration,
+and re-enabled with @code{sb-ext:enable-package-locks} declaration.
Example:
,@@body)))
@end lisp
-@subsubsection Interned symbols
+@subsubsection Other Operations
+
+If an non-lexical operation violates a package lock, a continuable
+error that is of a subtype of @code{sb-ext:package-lock-violation}
+(subtype of @code{package-error}) is signalled when the operation is
+attempted.
+
+Additional restarts may be established for continuable package lock
+violations for interactive use.
+
+The actual type of the error depends on circumstances that caused the
+violation: operations on packages signal errors of type
+@code{sb-ext:package-locked-error}, and operations on symbols signal
+errors of type @code{sb-ext:symbol-package-locked-error}.
+
-If compiled code contains interned symbols, then loading that code
+@node Package Locks in Compiled Code
+@subsection Package Locks in Compiled Code
+
+@subsubsection Interned Symbols
+
+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.
-@subsubsection 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
-code are not the same during loading of the code or execution.
+With the exception of interned symbols, behaviour is unspecified if
+package locks affecting compiled code are not the same during loading
+of the code or execution.
Specifically, code compiled with packages unlocked may or may not fail
to signal package-lock-violations even if the packages are locked at
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 negligible
performance penalty in compiled code as long as they are not violated.
@node Operations Violating Package Locks
@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
@item
Deleting a package.
+@item
+Adding a new package local nickname to a package.
+
+@item
+Removing an existing package local nickname to a package.
+
@end enumerate
@subsubsection Operations on Symbols
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)
@item
Using it as the class-name argument to setf of find-class.
+@item
+Defining it as a hash table test using @code{sb-ext:define-hash-table-test}.
+
@end enumerate
@node Package Lock Dictionary
@section Package Lock Dictionary
-@deftp {Declaration} sb-ext:disable-package-locks
+@deffn {Declaration} @sbext{disable-package-locks}
Syntax: @code{(sb-ext:disable-package-locks symbol*)}
in the lexical scope of the declaration. Disabling locks on symbols
whose home package is unlocked, or disabling an already disabled lock,
has no effect.
-@end deftp
+@end deffn
-@deftp {Declaration} sb-ext:enable-package-locks
+@deffn {Declaration} @sbext{enable-package-locks}
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.
-@end deftp
+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} declaration, or
+enabling locks that are already enabled has no effect.
+@end deffn
@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 @sbext{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 @cl{defpackage} name [[option]]* @result{} package
Options are extended to include the following:
projects / sbcl.git / blobdiff