0.9.9.33:

[sbcl.git] / doc / manual / package-locks-extended.texinfo

diff --git a/doc/manual/package-locks-extended.texinfo b/doc/manual/package-locks-extended.texinfo
index 8a1435d..8cb8a74 100644 (file)
--- 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
+locksing 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
 
 @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::     
 * Implementation Packages::     

-* Package Locked Errors::       
-* Package Locks in Compiled Code::               

 * Package Lock Violations::     
 * Package Lock Violations::     

-* Package Lock Dictionary::
+* Package Locks in Compiled Code::  
+* Operations Violating Package Locks::  

 @end menu
 
 @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}).
 
 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
 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
 
 Each package has a list of associated implementation packages. A
 locked package, and the symbols whose home package it is, can be

@@ -45,8 +62,15 @@ Unless explicitly altered by @code{defpackage},
 @code{sb-ext:remove-implementation-package} each package is its own
 (only) implementation package.
 
 @code{sb-ext:remove-implementation-package} each package is its own
 (only) implementation package.
 

-@node Package Locked Errors
-@section Package Locked Errors
+@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

 
 If an operation violates a package lock, a continuable error that is
 of a subtype of @code{sb-ext:package-lock-violation} (subtype of
 
 If an operation violates a package lock, a continuable error that is
 of a subtype of @code{sb-ext:package-lock-violation} (subtype of

@@ -61,15 +85,27 @@ violation: operations on packages signal errors of type
 errors of type @code{sb-ext:symbol-package-locked-error}.
 
 @node Package Locks in Compiled Code
 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
+@subsection Package Locks in Compiled Code
+
+@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

 
 Compiling lexical binding constructs or lexical declarations that
 
 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}.
+violate package locks causes 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}.

 
 Package locks affecting both lexical bindings and declarations can be
 disabled at compile-time with @code{sb-ext:disable-package-locks}
 
 Package locks affecting both lexical bindings and declarations can be
 disabled at compile-time with @code{sb-ext:disable-package-locks}

@@ -91,13 +127,13 @@ Example:
        ,@@body)))
 @end lisp
 
        ,@@body)))
 @end lisp
 

-@subsection Interned symbols
+@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
 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
 
 With the exception of the aforementioned contructs, and interned
 symbols, behaviour is unspecified if package locks affecting compiled

@@ -109,20 +145,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.
 
 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.
 
 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
 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
 
 @enumerate
 @item

@@ -151,7 +187,7 @@ Deleting a package.
 
 @end enumerate
 
 
 @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
 
 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 +201,10 @@ apparent violated package.
 Example:
 
 @lisp
 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)
 
 (defclass foo:point ()
   ((x :accessor bar:x)

@@ -271,17 +307,17 @@ has no effect.
 
 Syntax: @code{(sb-ext:enable-package-locks symbol*)}
 
 
 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
 
 @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.
 
 Returns the symbol that caused the @code{symbol-package-locked-error}
 condition.

@@ -297,7 +333,7 @@ condition.
 @include macro-sb-ext-without-package-locks.texinfo
 @include macro-sb-ext-with-unlocked-packages.texinfo
 
 @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:
 
 
 Options are extended to include the following: