1.0.8.48: Update comment.
[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 locking 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 @subsubsection Lexical Bindings and Declarations
76 @findex let
77 @findex let*
78 @findex flet
79 @findex labels
80 @findex macrolet
81 @findex symbol-macrolet
82 @findex declare
83 @cindex Declarations
84 @findex sb-ext:disable-package-locks
85 @findex sb-ext:enable-package-locks
86 @findex disable-package-locks
87 @findex enable-package-locks
88
89 Lexical bindings or declarations that violate package locks cause
90 result in a @code{program-error} being signalled at when the form that
91 violates package locks would be executed.
92
93 A complete listing of operators affect by this is: @code{let},
94 @code{let*}, @code{flet}, @code{labels}, @code{macrolet}, and
95 @code{symbol-macrolet}, @code{declare}.
96
97 Package locks affecting both lexical bindings and declarations can be
98 disabled locally with @code{sb-ext:disable-package-locks} declaration,
99 and re-enabled with @code{sb-ext:enable-package-locks} declaration.
100
101 Example:
102
103 @lisp
104 (in-package :locked)
105
106 (defun foo () ...)
107
108 (defmacro with-foo (&body body)
109   `(locally (declare (disable-package-locks locked:foo))
110      (flet ((foo () ...))
111        (declare (enable-package-locks locked:foo)) ; re-enable for body
112        ,@@body)))
113 @end lisp
114
115 @subsubsection Other Operations
116
117 If an non-lexical operation violates a package lock, a continuable
118 error that is of a subtype of @code{sb-ext:package-lock-violation}
119 (subtype of @code{package-error}) is signalled when the operation is
120 attempted.
121
122 Additional restarts may be established for continuable package lock
123 violations for interactive use.
124
125 The actual type of the error depends on circumstances that caused the
126 violation: operations on packages signal errors of type
127 @code{sb-ext:package-locked-error}, and operations on symbols signal
128 errors of type @code{sb-ext:symbol-package-locked-error}.
129
130
131 @node Package Locks in Compiled Code
132 @subsection Package Locks in Compiled Code
133
134 @subsubsection Interned Symbols
135
136 If file-compiled code contains interned symbols, then loading that code
137 into an image without the said symbols will not cause a package lock
138 violation, even if the packages in question are locked.
139
140 @subsubsection Other Limitations on Compiled Code
141
142 With the exception of interned symbols, behaviour is unspecified if
143 package locks affecting compiled code are not the same during loading
144 of the code or execution.
145
146 Specifically, code compiled with packages unlocked may or may not fail
147 to signal package-lock-violations even if the packages are locked at
148 runtime, and code compiled with packages locked may or may not signal
149 spurious package-lock-violations at runtime even if the packages are
150 unlocked.
151
152 In practice all this means that package-locks have a neglible
153 performance penalty in compiled code as long as they are not violated.
154
155 @node Operations Violating Package Locks
156 @subsection Operations Violating Package Locks
157
158 @subsubsection Operations on Packages
159
160 The following actions cause a package lock violation if the package
161 operated on is locked, and @code{*package*} is not an implementation
162 package of that package, and the action would cause a change in the
163 state of the package (so e.g. exporting already external symbols is
164 never a violation). Package lock violations caused by these operations
165 signal errors of type @code{sb-ext:package-locked-error}.
166
167 @enumerate
168 @item
169 Shadowing a symbol in a package.
170
171 @item
172 Importing a symbol to a package.
173
174 @item
175 Uninterning a symbol from a package.
176
177 @item
178 Exporting a symbol from a package.
179
180 @item
181 Unexporting a symbol from a package.
182
183 @item
184 Changing the packages used by a package.
185
186 @item
187 Renaming a package.
188
189 @item
190 Deleting a package.
191
192 @end enumerate
193
194 @subsubsection Operations on Symbols
195
196 Following actions cause a package lock violation if the home package
197 of the symbol operated on is locked, and @code{*package*} is not an
198 implementation package of that package. Package lock violations caused
199 by these action signal errors of type
200 @code{sb-ext:symbol-package-locked-error}.
201
202 These actions cause only one package lock violation per lexically
203 apparent violated package.
204
205 Example:
206
207 @lisp
208 ;;; Packages FOO and BAR are locked.
209 ;;;
210 ;;; Two lexically apparent violated packages: exactly two
211 ;;; package-locked-errors will be signalled.
212
213 (defclass foo:point ()
214   ((x :accessor bar:x)
215    (y :accessor bar:y)))
216 @end lisp
217
218 @enumerate
219 @item
220 Binding or altering its value lexically or dynamically, or
221 establishing it as a symbol-macro.
222
223 Exceptions:
224
225 @itemize @minus
226 @item
227 If the symbol is not defined as a constant, global symbol-macro or a
228 global dynamic variable, it may be lexically bound or established as a
229 local symbol macro.
230
231 @item
232 If the symbol is defined as a global dynamic variable, it may be
233 assigned or bound.
234
235 @end itemize
236
237 @item
238 Defining, undefining, or binding it, or its setf name as a function.
239
240 Exceptions:
241
242 @itemize @minus
243 @item
244 If the symbol is not defined as a function, macro, or special operator
245 it and its setf name may be lexically bound as a function.
246
247 @end itemize
248
249 @item
250 Defining, undefining, or binding it as a macro or compiler macro.
251
252 Exceptions:
253
254 @itemize @minus
255 @item
256 If the symbol is not defined as a function, macro, or special operator
257 it may be lexically bound as a macro.
258
259 @end itemize
260
261 @item
262 Defining it as a type specifier or structure.
263
264 @item
265 Defining it as a declaration with a declaration proclamation.
266
267 @item
268 Declaring or proclaiming it special.
269
270 @item
271 Declaring or proclaiming its type or ftype.
272
273 Exceptions:
274
275 @itemize @minus
276 @item
277 If the symbol may be lexically bound, the type of that binding may be
278 declared.
279
280 @item
281 If the symbol may be lexically bound as a function, the ftype of that
282 binding may be declared.
283
284 @end itemize
285
286 @item
287 Defining a setf expander for it.
288
289 @item
290 Defining it as a method combination type.
291
292 @item
293 Using it as the class-name argument to setf of find-class.
294
295 @end enumerate
296
297 @node Package Lock Dictionary
298 @section Package Lock Dictionary
299
300 @deftp {Declaration} sb-ext:disable-package-locks
301
302 Syntax: @code{(sb-ext:disable-package-locks symbol*)}
303
304 Disables package locks affecting the named symbols during compilation
305 in the lexical scope of the declaration. Disabling locks on symbols
306 whose home package is unlocked, or disabling an already disabled lock,
307 has no effect.
308 @end deftp
309
310 @deftp {Declaration} sb-ext:enable-package-locks
311
312 Syntax: @code{(sb-ext:enable-package-locks symbol*)}
313
314 Re-enables package locks affecting the named symbols during compilation
315 in the lexical scope of the declaration. Enabling locks that were not
316 first disabled with @code{sb-ext:disable-package-locks} declararion, or
317 enabling locks that are already enabled has no effect.
318 @end deftp
319
320 @include condition-sb-ext-package-lock-violation.texinfo
321 @include condition-sb-ext-package-locked-error.texinfo
322 @include condition-sb-ext-symbol-package-locked-error.texinfo
323
324 @defun sb-ext:package-locked-error-symbol symbol-package-locked-error
325
326 Returns the symbol that caused the @code{symbol-package-locked-error}
327 condition.
328 @end defun
329
330 @include fun-sb-ext-package-locked-p.texinfo
331 @include fun-sb-ext-lock-package.texinfo
332 @include fun-sb-ext-unlock-package.texinfo
333 @include fun-sb-ext-package-implemented-by-list.texinfo
334 @include fun-sb-ext-package-implements-list.texinfo
335 @include fun-sb-ext-add-implementation-package.texinfo
336 @include fun-sb-ext-remove-implementation-package.texinfo
337 @include macro-sb-ext-without-package-locks.texinfo
338 @include macro-sb-ext-with-unlocked-packages.texinfo
339
340 @defmac defpackage name [[option]]* @result{} package
341
342 Options are extended to include the following:
343
344 @itemize
345 @item
346 @code{:lock} @var{boolean}
347
348 If the argument to @code{:lock} is @code{t}, the package is initially
349 locked.  If @code{:lock} is not provided it defaults to @code{nil}.
350
351 @item
352 @code{:implement} @var{package-designator}*
353
354 The package is added as an implementation package to the packages
355 named. If @code{:implement} is not provided, it defaults to the
356 package itself.
357 @end itemize
358
359 Example:
360
361 @lisp
362 (defpackage "FOO" (:export "BAR") (:lock t) (:implement))
363 (defpackage "FOO-INT" (:use "FOO") (:implement "FOO" "FOO-INT"))
364
365 ;;; is equivalent to
366
367 (defpackage "FOO") (:export "BAR"))
368 (lock-package "FOO")
369 (remove-implementation-package "FOO" "FOO")
370 (defpackage "FOO-INT" (:use "BAR"))
371 (add-implementation-package "FOO-INT" "FOO")
372 @end lisp
373 @end defmac