X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fpackage-locks-extended.texinfo;h=f99388854c6f6c63416af46f68e6a5d853ea513d;hb=2e498cbcb062ff8b6e21703838e214c6427bffe8;hp=8a1435d3470e12b2dbc2c79a6df94b2c032ad4fd;hpb=ff92598854bf7cae8d57fe49cef4d9a98e1ab345;p=sbcl.git diff --git a/doc/manual/package-locks-extended.texinfo b/doc/manual/package-locks-extended.texinfo index 8a1435d..f993888 100644 --- a/doc/manual/package-locks-extended.texinfo +++ b/doc/manual/package-locks-extended.texinfo @@ -1,26 +1,41 @@ -@include package-locks-basic.texinfo +@node Package Locks +@comment node-name, next, previous, up +@chapter Package Locks +@cindex Packages, locked -None of the following sections apply to SBCL built -without package locks. +None of the following sections apply to SBCL built without package +locking support. -The interface described here is experimental: incompatible changes -in future SBCL releases are possible, even expected. +The interface described here is experimental: incompatible changes in +future SBCL releases are possible, even expected: the concept of +``implementation packages'' and the associated operators may be renamed; +more operations (such as naming restarts or catch tags) may be added to +the the list of operations violating package locks. @menu -* Package Locking Overview:: +* Package Lock Concepts:: +* Package Lock Dictionary:: +@end menu + +@node Package Lock Concepts +@section Package Lock Concepts + +@menu +* Package Lock Overview:: * Implementation Packages:: -* Package Locked Errors:: -* Package Locks in Compiled Code:: * Package Lock Violations:: -* Package Lock Dictionary:: +* Package Locks in Compiled Code:: +* Operations Violating Package Locks:: @end menu -@node Package Locking Overview -@section Package Locking Overview -Package locks protect against unintentional modifications of a -package: they provide similar protection to user packages as is -mandated to @code{common-lisp} package by the ANSI specification. They -are not, and should not be used as a security measure. +@node Package Lock Overview +@comment node-name, next, previous, up +@subsection Package Locking Overview + +Package locks protect against unintentional modifications of a package: +they provide similar protection to user packages as is mandated to +@code{common-lisp} package by the ANSI specification. They are not, and +should not be used as, a security measure. Newly created packages are by default unlocked (see the @code{:lock} option to @code{defpackage}). @@ -33,7 +48,9 @@ ensure that various libraries don't pollute it without asking, but this is not currently done by default. @node Implementation Packages -@section Implementation Packages +@subsection Implementation Packages +@vindex *package* +@findex defpackage Each package has a list of associated implementation packages. A locked package, and the symbols whose home package it is, can be @@ -45,37 +62,41 @@ Unless explicitly altered by @code{defpackage}, @code{sb-ext:remove-implementation-package} each package is its own (only) implementation package. -@node Package Locked Errors -@section Package Locked Errors - -If an operation violates a package lock, a continuable error that is -of a subtype of @code{sb-ext:package-lock-violation} (subtype of -@code{package-error}) is signalled when the operation is attempted. - -Additional restarts may be established for continuable package lock -violations for interactive use. - -The actual type of the error depends on circumstances that caused the -violation: operations on packages signal errors of type -@code{sb-ext:package-locked-error}, and operations on symbols signal -errors of type @code{sb-ext:symbol-package-locked-error}. - -@node Package Locks in Compiled Code -@section Package Locks in Compiled Code - -@subsection Lexical bindings and declarations - -Compiling lexical binding constructs or lexical declarations that -violate package locks package cause a compile-time package-lock -violation. A complete listing of operators affect by this is: -@code{let}, @code{let*}, @code{flet}, @code{labels}, @code{macrolet}, -and @code{symbol-macrolet}, @code{declare}. +@node Package Lock Violations +@subsection Package Lock Violations +@tindex sb-ext:package-lock-violation +@tindex sb-ext:package-locked-error +@tindex sb-ext:symbol-package-locked-error +@tindex package-lock-violation +@tindex package-locked-error +@tindex symbol-package-locked-error +@tindex package-error + +@subsubsection Lexical Bindings and Declarations +@findex let +@findex let* +@findex flet +@findex labels +@findex macrolet +@findex symbol-macrolet +@findex declare +@cindex Declarations +@findex sb-ext:disable-package-locks +@findex sb-ext:enable-package-locks +@findex disable-package-locks +@findex enable-package-locks + +Lexical bindings or declarations that violate package locks cause +result in a @code{program-error} being signalled at when the form that +violates package locks would be executed. + +A complete listing of operators affect by this is: @code{let}, +@code{let*}, @code{flet}, @code{labels}, @code{macrolet}, and +@code{symbol-macrolet}, @code{declare}. Package locks affecting both lexical bindings and declarations can be -disabled at compile-time with @code{sb-ext:disable-package-locks} -declaration, and re-enabled with @code{sb-ext:enable-package-locks} -declaration. Constructs compiled with package locks thusly disabled -are guaranteed not to signal package lock violation errors at runtime. +disabled locally with @code{sb-ext:disable-package-locks} declaration, +and re-enabled with @code{sb-ext:enable-package-locks} declaration. Example: @@ -91,17 +112,36 @@ Example: ,@@body))) @end lisp -@subsection Interned symbols +@subsubsection Other Operations + +If an non-lexical operation violates a package lock, a continuable +error that is of a subtype of @code{sb-ext:package-lock-violation} +(subtype of @code{package-error}) is signalled when the operation is +attempted. + +Additional restarts may be established for continuable package lock +violations for interactive use. + +The actual type of the error depends on circumstances that caused the +violation: operations on packages signal errors of type +@code{sb-ext:package-locked-error}, and operations on symbols signal +errors of type @code{sb-ext:symbol-package-locked-error}. + -If compiled code contains interned symbols, then loading that code +@node Package Locks in Compiled Code +@subsection Package Locks in Compiled Code + +@subsubsection Interned Symbols + +If file-compiled code contains interned symbols, then loading that code into an image without the said symbols will not cause a package lock -violation even if the packages in question are locked. +violation, even if the packages in question are locked. -@subsection Other limitations on compiled code +@subsubsection Other Limitations on Compiled Code -With the exception of the aforementioned contructs, and interned -symbols, behaviour is unspecified if package locks affecting compiled -code are not the same during loading of the code or execution. +With the exception of interned symbols, behaviour is unspecified if +package locks affecting compiled code are not the same during loading +of the code or execution. Specifically, code compiled with packages unlocked may or may not fail to signal package-lock-violations even if the packages are locked at @@ -109,20 +149,20 @@ runtime, and code compiled with packages locked may or may not signal spurious package-lock-violations at runtime even if the packages are unlocked. -In practise all this means that package-locks have a neglible +In practice all this means that package-locks have a neglible performance penalty in compiled code as long as they are not violated. -@node Package Lock Violations -@section Package Lock Violations +@node Operations Violating Package Locks +@subsection Operations Violating Package Locks -@heading Operations on Packages +@subsubsection Operations on Packages -Following actions cause a package lock violation if the package +The following actions cause a package lock violation if the package operated on is locked, and @code{*package*} is not an implementation package of that package, and the action would cause a change in the -state of the package (eg. exporting already external symbols is -allowed). Package lock violations caused by these operations signal -errors of type @code{sb-ext:package-locked-error}. +state of the package (so e.g. exporting already external symbols is +never a violation). Package lock violations caused by these operations +signal errors of type @code{sb-ext:package-locked-error}. @enumerate @item @@ -151,7 +191,7 @@ Deleting a package. @end enumerate -@heading Operations on Symbols +@subsubsection Operations on Symbols Following actions cause a package lock violation if the home package of the symbol operated on is locked, and @code{*package*} is not an @@ -165,10 +205,10 @@ apparent violated package. Example: @lisp -;; Packages FOO and BAR are locked. -;; -;; Two lexically apparent violated packages: exactly two -;; package-locked-errors will be signalled. +;;; Packages FOO and BAR are locked. +;;; +;;; Two lexically apparent violated packages: exactly two +;;; package-locked-errors will be signalled. (defclass foo:point () ((x :accessor bar:x) @@ -271,17 +311,17 @@ has no effect. Syntax: @code{(sb-ext:enable-package-locks symbol*)} -Re-enables package locks affecting the named symbols during -compilation in the lexical scope of the declaration. Enabling locks -that were not first disabled with @code{sb-ext:disable-package-locks} -declararion, or enabling locks that are already enabled has no effect. +Re-enables package locks affecting the named symbols during compilation +in the lexical scope of the declaration. Enabling locks that were not +first disabled with @code{sb-ext:disable-package-locks} declararion, or +enabling locks that are already enabled has no effect. @end deftp @include condition-sb-ext-package-lock-violation.texinfo @include condition-sb-ext-package-locked-error.texinfo @include condition-sb-ext-symbol-package-locked-error.texinfo -@defun sb-ext:package-locked-error-symbol @var{symbol-package-locked-error} +@defun sb-ext:package-locked-error-symbol symbol-package-locked-error Returns the symbol that caused the @code{symbol-package-locked-error} condition. @@ -297,7 +337,7 @@ condition. @include macro-sb-ext-without-package-locks.texinfo @include macro-sb-ext-with-unlocked-packages.texinfo -@defmac defpackage name [[@var{option}]]* @result{} package +@defmac defpackage name [[option]]* @result{} package Options are extended to include the following: