doc/manual/package-locks-extended.texinfo

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