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 @item
 188 Adding a new package local nickname to a package.
 189
 190 @item
 191 Removing an existing package local nickname to a package.
 192
 193 @end enumerate
 194
 195 @subsubsection Operations on Symbols
 196
 197 Following actions cause a package lock violation if the home package
 198 of the symbol operated on is locked, and @code{*package*} is not an
 199 implementation package of that package. Package lock violations caused
 200 by these action signal errors of type
 201 @code{sb-ext:symbol-package-locked-error}.
 202
 203 These actions cause only one package lock violation per lexically
 204 apparent violated package.
 205
 206 Example:
 207
 208 @lisp
 209 ;;; Packages FOO and BAR are locked.
 210 ;;;
 211 ;;; Two lexically apparent violated packages: exactly two
 212 ;;; package-locked-errors will be signalled.
 213
 214 (defclass foo:point ()
 215   ((x :accessor bar:x)
 216    (y :accessor bar:y)))
 217 @end lisp
 218
 219 @enumerate
 220 @item
 221 Binding or altering its value lexically or dynamically, or
 222 establishing it as a symbol-macro.
 223
 224 Exceptions:
 225
 226 @itemize @minus
 227 @item
 228 If the symbol is not defined as a constant, global symbol-macro or a
 229 global dynamic variable, it may be lexically bound or established as a
 230 local symbol macro.
 231
 232 @item
 233 If the symbol is defined as a global dynamic variable, it may be
 234 assigned or bound.
 235
 236 @end itemize
 237
 238 @item
 239 Defining, undefining, or binding it, or its setf name as a function.
 240
 241 Exceptions:
 242
 243 @itemize @minus
 244 @item
 245 If the symbol is not defined as a function, macro, or special operator
 246 it and its setf name may be lexically bound as a function.
 247
 248 @end itemize
 249
 250 @item
 251 Defining, undefining, or binding it as a macro or compiler macro.
 252
 253 Exceptions:
 254
 255 @itemize @minus
 256 @item
 257 If the symbol is not defined as a function, macro, or special operator
 258 it may be lexically bound as a macro.
 259
 260 @end itemize
 261
 262 @item
 263 Defining it as a type specifier or structure.
 264
 265 @item
 266 Defining it as a declaration with a declaration proclamation.
 267
 268 @item
 269 Declaring or proclaiming it special.
 270
 271 @item
 272 Declaring or proclaiming its type or ftype.
 273
 274 Exceptions:
 275
 276 @itemize @minus
 277 @item
 278 If the symbol may be lexically bound, the type of that binding may be
 279 declared.
 280
 281 @item
 282 If the symbol may be lexically bound as a function, the ftype of that
 283 binding may be declared.
 284
 285 @end itemize
 286
 287 @item
 288 Defining a setf expander for it.
 289
 290 @item
 291 Defining it as a method combination type.
 292
 293 @item
 294 Using it as the class-name argument to setf of find-class.
 295
 296 @item
 297 Defining it as a hash table test using @code{sb-ext:define-hash-table-test}.
 298
 299 @end enumerate
 300
 301 @node Package Lock Dictionary
 302 @section Package Lock Dictionary
 303
 304 @deffn {Declaration} @sbext{disable-package-locks}
 305
 306 Syntax: @code{(sb-ext:disable-package-locks symbol*)}
 307
 308 Disables package locks affecting the named symbols during compilation
 309 in the lexical scope of the declaration. Disabling locks on symbols
 310 whose home package is unlocked, or disabling an already disabled lock,
 311 has no effect.
 312 @end deffn
 313
 314 @deffn {Declaration} @sbext{enable-package-locks}
 315
 316 Syntax: @code{(sb-ext:enable-package-locks symbol*)}
 317
 318 Re-enables package locks affecting the named symbols during compilation
 319 in the lexical scope of the declaration. Enabling locks that were not
 320 first disabled with @code{sb-ext:disable-package-locks} declaration, or
 321 enabling locks that are already enabled has no effect.
 322 @end deffn
 323
 324 @include condition-sb-ext-package-lock-violation.texinfo
 325 @include condition-sb-ext-package-locked-error.texinfo
 326 @include condition-sb-ext-symbol-package-locked-error.texinfo
 327
 328 @defun @sbext{package-locked-error-symbol} symbol-package-locked-error
 329
 330 Returns the symbol that caused the @code{symbol-package-locked-error}
 331 condition.
 332 @end defun
 333
 334 @include fun-sb-ext-package-locked-p.texinfo
 335 @include fun-sb-ext-lock-package.texinfo
 336 @include fun-sb-ext-unlock-package.texinfo
 337 @include fun-sb-ext-package-implemented-by-list.texinfo
 338 @include fun-sb-ext-package-implements-list.texinfo
 339 @include fun-sb-ext-add-implementation-package.texinfo
 340 @include fun-sb-ext-remove-implementation-package.texinfo
 341 @include macro-sb-ext-without-package-locks.texinfo
 342 @include macro-sb-ext-with-unlocked-packages.texinfo
 343
 344 @defmac @cl{defpackage} name [[option]]* @result{} package
 345
 346 Options are extended to include the following:
 347
 348 @itemize
 349 @item
 350 @code{:lock} @var{boolean}
 351
 352 If the argument to @code{:lock} is @code{t}, the package is initially
 353 locked.  If @code{:lock} is not provided it defaults to @code{nil}.
 354
 355 @item
 356 @code{:implement} @var{package-designator}*
 357
 358 The package is added as an implementation package to the packages
 359 named. If @code{:implement} is not provided, it defaults to the
 360 package itself.
 361 @end itemize
 362
 363 Example:
 364
 365 @lisp
 366 (defpackage "FOO" (:export "BAR") (:lock t) (:implement))
 367 (defpackage "FOO-INT" (:use "FOO") (:implement "FOO" "FOO-INT"))
 368
 369 ;;; is equivalent to
 370
 371 (defpackage "FOO") (:export "BAR"))
 372 (lock-package "FOO")
 373 (remove-implementation-package "FOO" "FOO")
 374 (defpackage "FOO-INT" (:use "BAR"))
 375 (add-implementation-package "FOO-INT" "FOO")
 376 @end lisp
 377 @end defmac