X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fpackage-locks-extended.texinfo;h=4e3456075696513e4a042d4eedb95ed8027c7097;hb=a01e7ac2e8a9f3afae8f759381a0829fceb5bfde;hp=b950dc8e7238f66560d3da955f73f3a20772a44d;hpb=c696666acb1e79504d3c49283288ba5c35180e71;p=sbcl.git diff --git a/doc/manual/package-locks-extended.texinfo b/doc/manual/package-locks-extended.texinfo index b950dc8..4e34560 100644 --- a/doc/manual/package-locks-extended.texinfo +++ b/doc/manual/package-locks-extended.texinfo @@ -1,39 +1,41 @@ @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 -locksing support. +locking support. The interface described here is experimental: incompatible changes in -future SBCL releases are possible, even expected: most notably the -consept of implementation packages and the associated operators may be -renamed. +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 list of operations violating package locks. @menu -* Package Lock Concepts:: -* Package Lock Dictionary:: +* Package Lock Concepts:: +* Package Lock Dictionary:: @end menu @node Package Lock Concepts @section Package Lock Concepts @menu -* Package Lock Overview:: +* Package Lock Overview:: * Implementation Packages:: -* Package Lock Violations:: -* Package Locks in Compiled Code:: -* Operations Violating Package Locks:: +* Package Lock Violations:: +* Package Locks in Compiled Code:: +* Operations Violating Package Locks:: @end menu @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. +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}). @@ -47,6 +49,8 @@ but this is not currently done by default. @node 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 @@ -60,35 +64,39 @@ Unless explicitly altered by @code{defpackage}, @node Package Lock Violations @subsection Package Lock Violations - -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 -@subsection Package Locks in Compiled Code - -@subsubsection Lexical bindings and declarations - -Compiling lexical binding constructs or lexical declarations that -violate package locks causes a compile-time package-lock violation. A -complete listing of operators affect by this is: @code{let}, +@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: @@ -104,17 +112,36 @@ Example: ,@@body))) @end lisp -@subsubsection 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}. + + +@node Package Locks in Compiled Code +@subsection Package Locks in Compiled Code + +@subsubsection Interned Symbols -If compiled code contains interned symbols, then loading that code +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. -@subsubsection 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 @@ -122,7 +149,7 @@ 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 negligible performance penalty in compiled code as long as they are not violated. @node Operations Violating Package Locks @@ -130,12 +157,12 @@ performance penalty in compiled code as long as they are not violated. @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 @@ -178,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) @@ -284,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} declaration, 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. @@ -310,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: