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