doc/manual/package-locks-extended.texinfo

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