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 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 negligible
 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} declaration, 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