2 @comment node-name, next, previous, up
4 @cindex Packages, locked
6 None of the following sections apply to SBCL built without package
9 The interface described here is experimental: incompatible changes in
10 future SBCL releases are possible, even expected: most notably the
11 consept of implementation packages and the associated operators may be
15 * Package Lock Concepts::
16 * Package Lock Dictionary::
19 @node Package Lock Concepts
20 @section Package Lock Concepts
23 * Package Lock Overview::
24 * Implementation Packages::
25 * Package Lock Violations::
26 * Package Locks in Compiled Code::
27 * Operations Violating Package Locks::
30 @node Package Lock Overview
31 @comment node-name, next, previous, up
32 @subsection Package Locking Overview
34 Package locks protect against unintentional modifications of a
35 package: they provide similar protection to user packages as is
36 mandated to @code{common-lisp} package by the ANSI specification. They
37 are not, and should not be used as a security measure.
39 Newly created packages are by default unlocked (see the @code{:lock}
40 option to @code{defpackage}).
42 The package @code{common-lisp} and SBCL internal implementation
43 packages are locked by default, including @code{sb-ext}.
45 It may be beneficial to lock @code{common-lisp-user} as well, to
46 ensure that various libraries don't pollute it without asking,
47 but this is not currently done by default.
49 @node Implementation Packages
50 @subsection Implementation Packages
52 Each package has a list of associated implementation packages. A
53 locked package, and the symbols whose home package it is, can be
54 modified without violating package locks only when @code{*package*} is
55 bound to one of the implementation packages of the locked package.
57 Unless explicitly altered by @code{defpackage},
58 @code{sb-ext:add-implementation-package}, or
59 @code{sb-ext:remove-implementation-package} each package is its own
60 (only) implementation package.
62 @node Package Lock Violations
63 @subsection Package Lock Violations
65 If an operation violates a package lock, a continuable error that is
66 of a subtype of @code{sb-ext:package-lock-violation} (subtype of
67 @code{package-error}) is signalled when the operation is attempted.
69 Additional restarts may be established for continuable package lock
70 violations for interactive use.
72 The actual type of the error depends on circumstances that caused the
73 violation: operations on packages signal errors of type
74 @code{sb-ext:package-locked-error}, and operations on symbols signal
75 errors of type @code{sb-ext:symbol-package-locked-error}.
77 @node Package Locks in Compiled Code
78 @subsection Package Locks in Compiled Code
80 @subsubsection Lexical bindings and declarations
82 Compiling lexical binding constructs or lexical declarations that
83 violate package locks causes a compile-time package-lock violation. A
84 complete listing of operators affect by this is: @code{let},
85 @code{let*}, @code{flet}, @code{labels}, @code{macrolet}, and
86 @code{symbol-macrolet}, @code{declare}.
88 Package locks affecting both lexical bindings and declarations can be
89 disabled at compile-time with @code{sb-ext:disable-package-locks}
90 declaration, and re-enabled with @code{sb-ext:enable-package-locks}
91 declaration. Constructs compiled with package locks thusly disabled
92 are guaranteed not to signal package lock violation errors at runtime.
101 (defmacro with-foo (&body body)
102 `(locally (declare (disable-package-locks locked:foo))
104 (declare (enable-package-locks locked:foo)) ; re-enable for body
108 @subsubsection Interned symbols
110 If compiled code contains interned symbols, then loading that code
111 into an image without the said symbols will not cause a package lock
112 violation even if the packages in question are locked.
114 @subsubsection Other limitations on compiled code
116 With the exception of the aforementioned contructs, and interned
117 symbols, behaviour is unspecified if package locks affecting compiled
118 code are not the same during loading of the code or execution.
120 Specifically, code compiled with packages unlocked may or may not fail
121 to signal package-lock-violations even if the packages are locked at
122 runtime, and code compiled with packages locked may or may not signal
123 spurious package-lock-violations at runtime even if the packages are
126 In practise all this means that package-locks have a neglible
127 performance penalty in compiled code as long as they are not violated.
129 @node Operations Violating Package Locks
130 @subsection Operations Violating Package Locks
132 @subsubsection Operations on Packages
134 Following actions cause a package lock violation if the package
135 operated on is locked, and @code{*package*} is not an implementation
136 package of that package, and the action would cause a change in the
137 state of the package (eg. exporting already external symbols is
138 allowed). Package lock violations caused by these operations signal
139 errors of type @code{sb-ext:package-locked-error}.
143 Shadowing a symbol in a package.
146 Importing a symbol to a package.
149 Uninterning a symbol from a package.
152 Exporting a symbol from a package.
155 Unexporting a symbol from a package.
158 Changing the packages used by a package.
168 @subsubsection Operations on Symbols
170 Following actions cause a package lock violation if the home package
171 of the symbol operated on is locked, and @code{*package*} is not an
172 implementation package of that package. Package lock violations caused
173 by these action signal errors of type
174 @code{sb-ext:symbol-package-locked-error}.
176 These actions cause only one package lock violation per lexically
177 apparent violated package.
182 ;; Packages FOO and BAR are locked.
184 ;; Two lexically apparent violated packages: exactly two
185 ;; package-locked-errors will be signalled.
187 (defclass foo:point ()
189 (y :accessor bar:y)))
194 Binding or altering its value lexically or dynamically, or
195 establishing it as a symbol-macro.
201 If the symbol is not defined as a constant, global symbol-macro or a
202 global dynamic variable, it may be lexically bound or established as a
206 If the symbol is defined as a global dynamic variable, it may be
212 Defining, undefining, or binding it, or its setf name as a function.
218 If the symbol is not defined as a function, macro, or special operator
219 it and its setf name may be lexically bound as a function.
224 Defining, undefining, or binding it as a macro or compiler macro.
230 If the symbol is not defined as a function, macro, or special operator
231 it may be lexically bound as a macro.
236 Defining it as a type specifier or structure.
239 Defining it as a declaration with a declaration proclamation.
242 Declaring or proclaiming it special.
245 Declaring or proclaiming its type or ftype.
251 If the symbol may be lexically bound, the type of that binding may be
255 If the symbol may be lexically bound as a function, the ftype of that
256 binding may be declared.
261 Defining a setf expander for it.
264 Defining it as a method combination type.
267 Using it as the class-name argument to setf of find-class.
271 @node Package Lock Dictionary
272 @section Package Lock Dictionary
274 @deftp {Declaration} sb-ext:disable-package-locks
276 Syntax: @code{(sb-ext:disable-package-locks symbol*)}
278 Disables package locks affecting the named symbols during compilation
279 in the lexical scope of the declaration. Disabling locks on symbols
280 whose home package is unlocked, or disabling an already disabled lock,
284 @deftp {Declaration} sb-ext:enable-package-locks
286 Syntax: @code{(sb-ext:enable-package-locks symbol*)}
288 Re-enables package locks affecting the named symbols during
289 compilation in the lexical scope of the declaration. Enabling locks
290 that were not first disabled with @code{sb-ext:disable-package-locks}
291 declararion, or enabling locks that are already enabled has no effect.
294 @include condition-sb-ext-package-lock-violation.texinfo
295 @include condition-sb-ext-package-locked-error.texinfo
296 @include condition-sb-ext-symbol-package-locked-error.texinfo
298 @defun sb-ext:package-locked-error-symbol @var{symbol-package-locked-error}
300 Returns the symbol that caused the @code{symbol-package-locked-error}
304 @include fun-sb-ext-package-locked-p.texinfo
305 @include fun-sb-ext-lock-package.texinfo
306 @include fun-sb-ext-unlock-package.texinfo
307 @include fun-sb-ext-package-implemented-by-list.texinfo
308 @include fun-sb-ext-package-implements-list.texinfo
309 @include fun-sb-ext-add-implementation-package.texinfo
310 @include fun-sb-ext-remove-implementation-package.texinfo
311 @include macro-sb-ext-without-package-locks.texinfo
312 @include macro-sb-ext-with-unlocked-packages.texinfo
314 @defmac defpackage name [[@var{option}]]* @result{} package
316 Options are extended to include the following:
320 @code{:lock} @var{boolean}
322 If the argument to @code{:lock} is @code{t}, the package is initially
323 locked. If @code{:lock} is not provided it defaults to @code{nil}.
326 @code{:implement} @var{package-designator}*
328 The package is added as an implementation package to the packages
329 named. If @code{:implement} is not provided, it defaults to the
336 (defpackage "FOO" (:export "BAR") (:lock t) (:implement))
337 (defpackage "FOO-INT" (:use "FOO") (:implement "FOO" "FOO-INT"))
341 (defpackage "FOO") (:export "BAR"))
343 (remove-implementation-package "FOO" "FOO")
344 (defpackage "FOO-INT" (:use "BAR"))
345 (add-implementation-package "FOO-INT" "FOO")