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