From 4ad6d1b85a94e879ef5da95746cc6896b2906f6c Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Thu, 29 Apr 2021 13:14:18 -0700 Subject: add connattrs Signed-off-by: Sean Whitton --- doc/connections.rst | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'doc') diff --git a/doc/connections.rst b/doc/connections.rst index 5e54111..f66b207 100644 --- a/doc/connections.rst +++ b/doc/connections.rst @@ -44,6 +44,38 @@ connection really does require more I/O, such as in the case of ``:CHROOT.FORK`` connections, code can call ``LISP-CONNECTION-P``, and either signal an error, or fall back to another connection type. +Connection attributes ("connattrs") +----------------------------------- + +Information about hosts which cannot be known without looking at the host, or +for other reasons should not be recorded in consfigs, can be stored as +connection attributes, associated with the current connection. Typically +property combinators set and unset connattrs, and property ``:APPLY`` and +``:UNAPPLY`` subroutines read them. They can be used to create context for +the application of properties. Connection attributes are stored in a plist. +Property combinators use the ``WITH-CONNATTRS`` macro to set them, and +properties use ``GET-CONNATTR`` to read them. + +Like hostattrs, connection attributes are identified by keywords for connattrs +which are expected to be used in many contexts, and by other symbols for +connattrs which will be used only among a co-operating group of properties and +property combinators. However, unlike hostattrs, each connattr need not be a +list to which new items are pushed. + +By default the list of connattrs is reset when establishing a new connection +within the context of an existing connection. However, for some connattrs it +makes sense to propagate them along to the new connection. For example, a +list of connected hardware of a particular type might still be useful in the +context of a connection which chroots, as /dev might still give access to this +hardware. Implementations of the ``PROPAGATE-CONNATTR`` generic function can +be used to enable propagation where it makes sense. Methods can copy and +modify connattrs as appropriate; in the chroot example, paths might be updated +so that they are relative to the new filesystem root. + +The propagation of connattrs is currently limited to the establishing of +connections within the same Lisp image; i.e., connection types which start up +new Lisp images never propagate any existing connattrs. + Notes on particular connection types ------------------------------------ -- cgit v1.2.3