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: most notably the
  11 consept of implementation packages and the associated operators may be
  12 renamed.
  13
  14 @menu
  15 * Package Lock Concepts::
  16 * Package Lock Dictionary::
  17 @end menu
  18
  19 @node Package Lock Concepts
  20 @section Package Lock Concepts
  21
  22 @menu
  23 * Package Lock Overview::
  24 * Implementation Packages::
  25 * Package Lock Violations::
  26 * Package Locks in Compiled Code::
  27 * Operations Violating Package Locks::
  28 @end menu
  29
  30 @node Package Lock Overview
  31 @comment  node-name,  next,  previous,  up
  32 @subsection Package Locking Overview
  33
  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.
  38
  39 Newly created packages are by default unlocked (see the @code{:lock}
  40 option to @code{defpackage}).
  41
  42 The package @code{common-lisp} and SBCL internal implementation
  43 packages are locked by default, including @code{sb-ext}.
  44
  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.
  48
  49 @node Implementation Packages
  50 @subsection Implementation Packages
  51
  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.
  56
  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.
  61
  62 @node Package Lock Violations
  63 @subsection Package Lock Violations
  64
  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.
  68
  69 Additional restarts may be established for continuable package lock
  70 violations for interactive use.
  71
  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}.
  76
  77 @node Package Locks in Compiled Code
  78 @subsection Package Locks in Compiled Code
  79
  80 @subsubsection Lexical bindings and declarations
  81
  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}.
  87
  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.
  93
  94 Example:
  95
  96 @lisp
  97 (in-package :locked)
  98
  99 (defun foo () ...)
 100
 101 (defmacro with-foo (&body body)
 102   `(locally (declare (disable-package-locks locked:foo))
 103      (flet ((foo () ...))
 104        (declare (enable-package-locks locked:foo)) ; re-enable for body
 105        ,@@body)))
 106 @end lisp
 107
 108 @subsubsection Interned symbols
 109
 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.
 113
 114 @subsubsection Other limitations on compiled code
 115
 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.
 119
 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
 124 unlocked.
 125
 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.
 128
 129 @node Operations Violating Package Locks
 130 @subsection Operations Violating Package Locks
 131
 132 @subsubsection Operations on Packages
 133
 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}.
 140
 141 @enumerate
 142 @item
 143 Shadowing a symbol in a package.
 144
 145 @item
 146 Importing a symbol to a package.
 147
 148 @item
 149 Uninterning a symbol from a package.
 150
 151 @item
 152 Exporting a symbol from a package.
 153
 154 @item
 155 Unexporting a symbol from a package.
 156
 157 @item
 158 Changing the packages used by a package.
 159
 160 @item
 161 Renaming a package.
 162
 163 @item
 164 Deleting a package.
 165
 166 @end enumerate
 167
 168 @subsubsection Operations on Symbols
 169
 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}.
 175
 176 These actions cause only one package lock violation per lexically
 177 apparent violated package.
 178
 179 Example:
 180
 181 @lisp
 182 ;; Packages FOO and BAR are locked.
 183 ;;
 184 ;; Two lexically apparent violated packages: exactly two
 185 ;; package-locked-errors will be signalled.
 186
 187 (defclass foo:point ()
 188   ((x :accessor bar:x)
 189    (y :accessor bar:y)))
 190 @end lisp
 191
 192 @enumerate
 193 @item
 194 Binding or altering its value lexically or dynamically, or
 195 establishing it as a symbol-macro.
 196
 197 Exceptions:
 198
 199 @itemize @minus
 200 @item
 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
 203 local symbol macro.
 204
 205 @item
 206 If the symbol is defined as a global dynamic variable, it may be
 207 assigned or bound.
 208
 209 @end itemize
 210
 211 @item
 212 Defining, undefining, or binding it, or its setf name as a function.
 213
 214 Exceptions:
 215
 216 @itemize @minus
 217 @item
 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.
 220
 221 @end itemize
 222
 223 @item
 224 Defining, undefining, or binding it as a macro or compiler macro.
 225
 226 Exceptions:
 227
 228 @itemize @minus
 229 @item
 230 If the symbol is not defined as a function, macro, or special operator
 231 it may be lexically bound as a macro.
 232
 233 @end itemize
 234
 235 @item
 236 Defining it as a type specifier or structure.
 237
 238 @item
 239 Defining it as a declaration with a declaration proclamation.
 240
 241 @item
 242 Declaring or proclaiming it special.
 243
 244 @item
 245 Declaring or proclaiming its type or ftype.
 246
 247 Exceptions:
 248
 249 @itemize @minus
 250 @item
 251 If the symbol may be lexically bound, the type of that binding may be
 252 declared.
 253
 254 @item
 255 If the symbol may be lexically bound as a function, the ftype of that
 256 binding may be declared.
 257
 258 @end itemize
 259
 260 @item
 261 Defining a setf expander for it.
 262
 263 @item
 264 Defining it as a method combination type.
 265
 266 @item
 267 Using it as the class-name argument to setf of find-class.
 268
 269 @end enumerate
 270
 271 @node Package Lock Dictionary
 272 @section Package Lock Dictionary
 273
 274 @deftp {Declaration} sb-ext:disable-package-locks
 275
 276 Syntax: @code{(sb-ext:disable-package-locks symbol*)}
 277
 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,
 281 has no effect.
 282 @end deftp
 283
 284 @deftp {Declaration} sb-ext:enable-package-locks
 285
 286 Syntax: @code{(sb-ext:enable-package-locks symbol*)}
 287
 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.
 292 @end deftp
 293
 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
 297
 298 @defun sb-ext:package-locked-error-symbol @var{symbol-package-locked-error}
 299
 300 Returns the symbol that caused the @code{symbol-package-locked-error}
 301 condition.
 302 @end defun
 303
 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
 313
 314 @defmac defpackage name [[@var{option}]]* @result{} package
 315
 316 Options are extended to include the following:
 317
 318 @itemize
 319 @item
 320 @code{:lock} @var{boolean}
 321
 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}.
 324
 325 @item
 326 @code{:implement} @var{package-designator}*
 327
 328 The package is added as an implementation package to the packages
 329 named. If @code{:implement} is not provided, it defaults to the
 330 package itself.
 331 @end itemize
 332
 333 Example:
 334
 335 @lisp
 336 (defpackage "FOO" (:export "BAR") (:lock t) (:implement))
 337 (defpackage "FOO-INT" (:use "FOO") (:implement "FOO" "FOO-INT"))
 338
 339 ;;; is equivalent to
 340
 341 (defpackage "FOO") (:export "BAR"))
 342 (lock-package "FOO")
 343 (remove-implementation-package "FOO" "FOO")
 344 (defpackage "FOO-INT" (:use "BAR"))
 345 (add-implementation-package "FOO-INT" "FOO")
 346 @end lisp
 347 @end defmac