0.9.11.4
[sbcl.git] / doc / manual / package-locks-extended.texinfo
1 @node Package Locks
2 @comment  node-name,  next,  previous,  up
3 @chapter Package Locks
4 @cindex Packages, locked
5
6 None of the following sections apply to SBCL built without package
7 locksing support.
8
9 The interface described here is experimental: incompatible changes in
10 future SBCL releases are possible, even expected: the concept of
11 ``implementation packages'' and the associated operators may be renamed;
12 more operations (such as naming restarts or catch tags) may be added to
13 the the list of operations violating package locks.
14
15 @menu
16 * Package Lock Concepts::       
17 * Package Lock Dictionary::     
18 @end menu
19
20 @node Package Lock Concepts
21 @section Package Lock Concepts
22
23 @menu
24 * Package Lock Overview::       
25 * Implementation Packages::     
26 * Package Lock Violations::     
27 * Package Locks in Compiled Code::  
28 * Operations Violating Package Locks::  
29 @end menu
30
31 @node Package Lock Overview
32 @comment  node-name,  next,  previous,  up
33 @subsection Package Locking Overview
34
35 Package locks protect against unintentional modifications of a package:
36 they provide similar protection to user packages as is mandated to
37 @code{common-lisp} package by the ANSI specification. They are not, and
38 should not be used as, a security measure.
39
40 Newly created packages are by default unlocked (see the @code{:lock}
41 option to @code{defpackage}).
42
43 The package @code{common-lisp} and SBCL internal implementation
44 packages are locked by default, including @code{sb-ext}.
45
46 It may be beneficial to lock @code{common-lisp-user} as well, to
47 ensure that various libraries don't pollute it without asking,
48 but this is not currently done by default.
49
50 @node Implementation Packages
51 @subsection Implementation Packages
52 @vindex *package*
53 @findex defpackage
54
55 Each package has a list of associated implementation packages. A
56 locked package, and the symbols whose home package it is, can be
57 modified without violating package locks only when @code{*package*} is
58 bound to one of the implementation packages of the locked package.
59
60 Unless explicitly altered by @code{defpackage},
61 @code{sb-ext:add-implementation-package}, or
62 @code{sb-ext:remove-implementation-package} each package is its own
63 (only) implementation package.
64
65 @node Package Lock Violations
66 @subsection Package Lock Violations
67 @tindex sb-ext:package-lock-violation
68 @tindex sb-ext:package-locked-error
69 @tindex sb-ext:symbol-package-locked-error
70 @tindex package-lock-violation
71 @tindex package-locked-error
72 @tindex symbol-package-locked-error
73 @tindex package-error
74
75 If an operation violates a package lock, a continuable error that is
76 of a subtype of @code{sb-ext:package-lock-violation} (subtype of
77 @code{package-error}) is signalled when the operation is attempted.
78
79 Additional restarts may be established for continuable package lock
80 violations for interactive use.
81
82 The actual type of the error depends on circumstances that caused the
83 violation: operations on packages signal errors of type
84 @code{sb-ext:package-locked-error}, and operations on symbols signal
85 errors of type @code{sb-ext:symbol-package-locked-error}.
86
87 @node Package Locks in Compiled Code
88 @subsection Package Locks in Compiled Code
89
90 @subsubsection Lexical bindings and declarations
91 @findex let
92 @findex let*
93 @findex flet
94 @findex labels
95 @findex macrolet
96 @findex symbol-macrolet
97 @findex declare
98 @cindex Declarations
99 @findex sb-ext:disable-package-locks
100 @findex sb-ext:enable-package-locks
101 @findex disable-package-locks
102 @findex enable-package-locks
103
104 Compiling lexical binding constructs or lexical declarations that
105 violate package locks causes a compile-time package-lock violation. A
106 complete listing of operators affect by this is: @code{let},
107 @code{let*}, @code{flet}, @code{labels}, @code{macrolet}, and
108 @code{symbol-macrolet}, @code{declare}.
109
110 Package locks affecting both lexical bindings and declarations can be
111 disabled at compile-time with @code{sb-ext:disable-package-locks}
112 declaration, and re-enabled with @code{sb-ext:enable-package-locks}
113 declaration. Constructs compiled with package locks thusly disabled
114 are guaranteed not to signal package lock violation errors at runtime.
115
116 Example:
117
118 @lisp
119 (in-package :locked)
120
121 (defun foo () ...)
122
123 (defmacro with-foo (&body body)
124   `(locally (declare (disable-package-locks locked:foo))
125      (flet ((foo () ...))
126        (declare (enable-package-locks locked:foo)) ; re-enable for body
127        ,@@body)))
128 @end lisp
129
130 @subsubsection Interned symbols
131
132 If file-compiled code contains interned symbols, then loading that code
133 into an image without the said symbols will not cause a package lock
134 violation, even if the packages in question are locked.
135
136 @subsubsection Other limitations on compiled code
137
138 With the exception of the aforementioned contructs, and interned
139 symbols, behaviour is unspecified if package locks affecting compiled
140 code are not the same during loading of the code or execution.
141
142 Specifically, code compiled with packages unlocked may or may not fail
143 to signal package-lock-violations even if the packages are locked at
144 runtime, and code compiled with packages locked may or may not signal
145 spurious package-lock-violations at runtime even if the packages are
146 unlocked.
147
148 In practice all this means that package-locks have a neglible
149 performance penalty in compiled code as long as they are not violated.
150
151 @node Operations Violating Package Locks
152 @subsection Operations Violating Package Locks
153
154 @subsubsection Operations on Packages
155
156 The following actions cause a package lock violation if the package
157 operated on is locked, and @code{*package*} is not an implementation
158 package of that package, and the action would cause a change in the
159 state of the package (so e.g. exporting already external symbols is
160 never a violation). Package lock violations caused by these operations
161 signal errors of type @code{sb-ext:package-locked-error}.
162
163 @enumerate
164 @item
165 Shadowing a symbol in a package.
166
167 @item
168 Importing a symbol to a package.
169
170 @item
171 Uninterning a symbol from a package.
172
173 @item
174 Exporting a symbol from a package.
175
176 @item
177 Unexporting a symbol from a package.
178
179 @item
180 Changing the packages used by a package.
181
182 @item
183 Renaming a package.
184
185 @item
186 Deleting a package.
187
188 @end enumerate
189
190 @subsubsection Operations on Symbols
191
192 Following actions cause a package lock violation if the home package
193 of the symbol operated on is locked, and @code{*package*} is not an
194 implementation package of that package. Package lock violations caused
195 by these action signal errors of type
196 @code{sb-ext:symbol-package-locked-error}.
197
198 These actions cause only one package lock violation per lexically
199 apparent violated package.
200
201 Example:
202
203 @lisp
204 ;;; Packages FOO and BAR are locked.
205 ;;;
206 ;;; Two lexically apparent violated packages: exactly two
207 ;;; package-locked-errors will be signalled.
208
209 (defclass foo:point ()
210   ((x :accessor bar:x)
211    (y :accessor bar:y)))
212 @end lisp
213
214 @enumerate
215 @item
216 Binding or altering its value lexically or dynamically, or
217 establishing it as a symbol-macro.
218
219 Exceptions:
220
221 @itemize @minus
222 @item
223 If the symbol is not defined as a constant, global symbol-macro or a
224 global dynamic variable, it may be lexically bound or established as a
225 local symbol macro.
226
227 @item
228 If the symbol is defined as a global dynamic variable, it may be
229 assigned or bound.
230
231 @end itemize
232
233 @item
234 Defining, undefining, or binding it, or its setf name as a function.
235
236 Exceptions:
237
238 @itemize @minus
239 @item
240 If the symbol is not defined as a function, macro, or special operator
241 it and its setf name may be lexically bound as a function.
242
243 @end itemize
244
245 @item
246 Defining, undefining, or binding it as a macro or compiler macro.
247
248 Exceptions:
249
250 @itemize @minus
251 @item
252 If the symbol is not defined as a function, macro, or special operator
253 it may be lexically bound as a macro.
254
255 @end itemize
256
257 @item
258 Defining it as a type specifier or structure.
259
260 @item
261 Defining it as a declaration with a declaration proclamation.
262
263 @item
264 Declaring or proclaiming it special.
265
266 @item
267 Declaring or proclaiming its type or ftype.
268
269 Exceptions:
270
271 @itemize @minus
272 @item
273 If the symbol may be lexically bound, the type of that binding may be
274 declared.
275
276 @item
277 If the symbol may be lexically bound as a function, the ftype of that
278 binding may be declared.
279
280 @end itemize
281
282 @item
283 Defining a setf expander for it.
284
285 @item
286 Defining it as a method combination type.
287
288 @item
289 Using it as the class-name argument to setf of find-class.
290
291 @end enumerate
292
293 @node Package Lock Dictionary
294 @section Package Lock Dictionary
295
296 @deftp {Declaration} sb-ext:disable-package-locks
297
298 Syntax: @code{(sb-ext:disable-package-locks symbol*)}
299
300 Disables package locks affecting the named symbols during compilation
301 in the lexical scope of the declaration. Disabling locks on symbols
302 whose home package is unlocked, or disabling an already disabled lock,
303 has no effect.
304 @end deftp
305
306 @deftp {Declaration} sb-ext:enable-package-locks
307
308 Syntax: @code{(sb-ext:enable-package-locks symbol*)}
309
310 Re-enables package locks affecting the named symbols during compilation
311 in the lexical scope of the declaration. Enabling locks that were not
312 first disabled with @code{sb-ext:disable-package-locks} declararion, or
313 enabling locks that are already enabled has no effect.
314 @end deftp
315
316 @include condition-sb-ext-package-lock-violation.texinfo
317 @include condition-sb-ext-package-locked-error.texinfo
318 @include condition-sb-ext-symbol-package-locked-error.texinfo
319
320 @defun sb-ext:package-locked-error-symbol symbol-package-locked-error
321
322 Returns the symbol that caused the @code{symbol-package-locked-error}
323 condition.
324 @end defun
325
326 @include fun-sb-ext-package-locked-p.texinfo
327 @include fun-sb-ext-lock-package.texinfo
328 @include fun-sb-ext-unlock-package.texinfo
329 @include fun-sb-ext-package-implemented-by-list.texinfo
330 @include fun-sb-ext-package-implements-list.texinfo
331 @include fun-sb-ext-add-implementation-package.texinfo
332 @include fun-sb-ext-remove-implementation-package.texinfo
333 @include macro-sb-ext-without-package-locks.texinfo
334 @include macro-sb-ext-with-unlocked-packages.texinfo
335
336 @defmac defpackage name [[option]]* @result{} package
337
338 Options are extended to include the following:
339
340 @itemize
341 @item
342 @code{:lock} @var{boolean}
343
344 If the argument to @code{:lock} is @code{t}, the package is initially
345 locked.  If @code{:lock} is not provided it defaults to @code{nil}.
346
347 @item
348 @code{:implement} @var{package-designator}*
349
350 The package is added as an implementation package to the packages
351 named. If @code{:implement} is not provided, it defaults to the
352 package itself.
353 @end itemize
354
355 Example:
356
357 @lisp
358 (defpackage "FOO" (:export "BAR") (:lock t) (:implement))
359 (defpackage "FOO-INT" (:use "FOO") (:implement "FOO" "FOO-INT"))
360
361 ;;; is equivalent to
362
363 (defpackage "FOO") (:export "BAR"))
364 (lock-package "FOO")
365 (remove-implementation-package "FOO" "FOO")
366 (defpackage "FOO-INT" (:use "BAR"))
367 (add-implementation-package "FOO-INT" "FOO")
368 @end lisp
369 @end defmac