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