doc/cmu-user/package-locks.tex

   1 \section{Package Locks}
   2 \cindex{package locks}
   3
   4 \cmucl{} provides two types of package locks, as an extension to the
   5 ANSI Common Lisp standard. The package-lock protects a package from
   6 changes in its structure (the set of exported symbols, its use list,
   7 etc). The package-definition-lock protects the symbols in the package
   8 from being redefined due to the execution of a \code{defun},
   9 \code{defmacro}, \code{defstruct}, \code{deftype} or \code{defclass}
  10 form.
  11
  12
  13 \subsection{Rationale}
  14
  15 Package locks are an aid to program development, by helping to detect
  16 inadvertent name collisions and function redefinitions. They are
  17 consistent with the principle that a package ``belongs to'' its
  18 implementor, and that noone other than the package's developer should
  19 be making or modifying definitions on symbols in that package. Package
  20 locks are compatible with the ANSI Common Lisp standard, which states
  21 that the consequences of redefining functions in the
  22 \code{COMMON-LISP} package are undefined.
  23
  24 Violation of a package lock leads to a continuable error of type
  25 \code{lisp::package-locked-error} being signaled. The user may choose
  26 to ignore the lock and proceed, or to abort the computation. Two other
  27 restarts are available, one which disables all locks on all packages,
  28 and one to disable only the package-lock or package-definition-lock
  29 that was tripped.
  30
  31 The following transcript illustrates the behaviour seen when
  32 attempting to redefine a standard macro in the \code{COMMON-LISP}
  33 package, or to redefine a function in one of \cmucl{}'s
  34 implementation-defined packages:
  35
  36 {\small
  37 \begin{verbatim}
  38 CL-USER> (defmacro 1+ (x) (* x 2))
  39 Attempt to modify the locked package COMMON-LISP, by defining macro 1+
  40    [Condition of type LISP::PACKAGE-LOCKED-ERROR]
  41
  42 Restarts:
  43   0: [continue      ] Ignore the lock and continue
  44   1: [unlock-package] Disable the package's definition-lock then continue
  45   2: [unlock-all    ] Unlock all packages, then continue
  46   3: [abort         ] Return to Top-Level.
  47
  48 CL-USER> (defun ext:gc () t)
  49 Attempt to modify the locked package EXTENSIONS, by redefining function GC
  50    [Condition of type LISP::PACKAGE-LOCKED-ERROR]
  51
  52 Restarts:
  53   0: [continue      ] Ignore the lock and continue
  54   1: [unlock-package] Disable package's definition-lock, then continue
  55   2: [unlock-all    ] Disable all package locks, then continue
  56   3: [abort         ] Return to Top-Level.
  57 \end{verbatim}
  58
  59
  60 The following transcript illustrates the behaviour seen when an
  61 attempt to modify the structure of a package is made:
  62
  63 \begin{verbatim}
  64 CL-USER> (unexport 'load-foreign :ext)
  65 Attempt to modify the locked package EXTENSIONS, by unexporting symbols LOAD-FOREIGN
  66    [Condition of type lisp::package-locked-error]
  67
  68 Restarts:
  69   0: [continue      ] Ignore the lock and continue
  70   1: [unlock-package] Disable package's lock then continue
  71   2: [unlock-all    ] Unlock all packages, then continue
  72   3: [abort         ] Return to Top-Level.
  73 \end{verbatim}
  74 }
  75
  76 The \code{COMMON-LISP} package and the \cmucl{}-specific
  77 implementation packages are locked on startup. Users can lock their
  78 own packages by using the \code{ext:package-lock} and
  79 \code{ext:package-definition-lock} accessors.
  80
  81
  82
  83 \subsection{Disabling package locks}
  84
  85 A package's locks can be enabled or disabled by using the
  86 \code{ext:package-lock} and \code{ext:package-definition-lock}
  87 accessors, as follows:
  88
  89 \begin{lisp}
  90    (setf (ext:package-lock (find-package "UNIX")) nil)
  91    (setf (ext:package-definition-lock (find-package "UNIX")) nil)
  92 \end{lisp}
  93
  94
  95 \begin{defun}{ext:}{package-lock}{\var{package}}
  96   This function is an accessor for a package's structural lock, which
  97   protects it against modifications to its list of exported symbols.
  98 \end{defun}
  99
 100
 101 \begin{defun}{ext:}{package-definition-lock}{\var{package}}
 102   This function is an accessor for a package's definition-lock, which
 103   protects symbols in that package from redefinition. As well as
 104   protecting the symbol's fdefinition from change, attempts to change
 105   the symbol's definition using \code{defstruct}, \code{defclass} or
 106   \code{deftype} will be trapped.
 107 \end{defun}
 108
 109
 110 \begin{defmac}{ext:}{without-package-locks}{\args{\amprest{} \var{body}}}
 111   This macro can be used to execute forms with all package locks (both
 112   structure and definition locks) disabled.
 113 \end{defmac}
 114
 115
 116 \begin{defun}{ext:}{unlock-all-packages}{}
 117   This function disables both structure and definition locks on all
 118   currently defined packages. Note that package locks are reset when
 119   \cmucl{} is restarted, so the effect of this function is limited to
 120   the current session.
 121 \end{defun}
 122
 123
 124 % EOF