doc/manual/package-locks-extended.texinfo

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