[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
scratch/sqlite 39ca2b4: Document multisession variables
From: |
Lars Ingebrigtsen |
Subject: |
scratch/sqlite 39ca2b4: Document multisession variables |
Date: |
Sun, 12 Dec 2021 02:43:46 -0500 (EST) |
branch: scratch/sqlite
commit 39ca2b45f06c95e5a9c07cb87a0fa8dfbe050bd6
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>
Document multisession variables
---
doc/lispref/elisp.texi | 1 +
doc/lispref/variables.texi | 88 +++++++++++++++++++++++++++++++++++++++++
lisp/emacs-lisp/multisession.el | 2 +-
3 files changed, 90 insertions(+), 1 deletion(-)
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index b773ba8..7bb2091 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -526,6 +526,7 @@ Variables
* Variables with Restricted Values:: Non-constant variables whose value can
@emph{not} be an arbitrary Lisp object.
* Generalized Variables:: Extending the concept of variables.
+* Multisession Variables:: Variables that survive restarting Emacs.
Scoping Rules for Variable Bindings
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index abef0b3..844d125 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -44,6 +44,7 @@ representing the variable.
* Variables with Restricted Values:: Non-constant variables whose value can
@emph{not} be an arbitrary Lisp object.
* Generalized Variables:: Extending the concept of variables.
+* Multisession Variables:: Variables that survive restarting Emacs.
@end menu
@node Global Variables
@@ -2752,3 +2753,90 @@ form that has not already had an appropriate expansion
defined. In
Common Lisp, this is not an error since the function @code{(setf
@var{func})} might be defined later.
@end quotation
+
+@node Multisession Variables
+@section Multisession Variables
+
+@cindex multisession variable
+ When you set a variable to a value and then close Emacs and restart
+Emacs, this value won't be automatically restored. Users usually set
+normal variables in their startup files, or use Customize to set a
+user option permanently, and various packages have various files that
+they store the data in (Gnus stores this in @file{.newsrc.eld} and the
+URL library stores cookies in @file{~/.emacs.d/url/cookies}.
+
+For things in between these two extremes (i.e., configuration which
+goes in the startup file, and massive application state that goes into
+separate files), Emacs provides a facility to replicate data between
+sessions called @dfn{multisession variables}. To give you an idea of
+how these are meant to be used, here's a small example:
+
+@lisp
+(define-multisession-variable foo-var 0)
+(defun my-adder (num)
+ (interactive "nAdd number: ")
+ (setf (multisession-value foo)
+ (+ (multisession-value foo) num))
+ (message "The new number is: %s" (multisession-value foo)))
+@end lisp
+
+This defines the variable @code{foo-var} and binds it to a special
+multisession object which is initialized with the value @samp{0} (if
+it doesn't already exist from a previous session). The
+@code{my-adder} function queries the user for a number, adds this to
+the old (possibly saved value), and then saves the new value.
+
+This facility isn't meant to be used for huge data structures, but
+should be reasonably performant for most values.
+
+@defmac define-multisession-variable name initial-value &optional doc &rest
args
+This macro defines @var{name} as a multisession variable, with using
+@var{initial-value} is this variable hasn't been stored earlier.
+@var{doc} is the doc string, and some keyword arguments are possible:
+
+@table @code
+@item :package symbol
+This keyword says what package a multisession variable belongs to.
+The combination of @var{package} and @var{name} has to be unique. If
+@var{package} isn't given, this will default to the first ``section''
+of the @var{name} symbol name. For instance, if @var{name} is
+@code{foo-var} and @var{package} isn't given, @var{package} will
+default to @code{foo}.
+
+@item :synchronized bool
+By default, multisession variables are @dfn{synchronized}. This means
+that if there's two concurrent Emacs instances running, and the other
+Emacs changes the multisession variable @code{foo-var}, the current
+Emacs instance will retrieve that data when accessing the value. If
+@var{synchronized} is @code{nil}, this won't happen, and the variable
+in all Emacs sessions will be independent.
+@end table
+@end defmac
+
+@defun multisession-value variable
+This function returns the current value of @var{variable}. If this
+variable hasn't been accessed before in this Emacs session, or if it's
+changed externally, it will be read in from external storage. If not,
+the current value in this session is returned as is.
+
+Values retrieved via @code{multisession-value} may or may not be
+@code{eq} to each other, but they will always be @code{equal}.
+
+This is a generalized variable (@pxref{Generalized Variables}), so the
+way to update a variable is to say, for instance:
+
+@lisp
+(setf (multisession-value foo-bar) 'zot)
+@end lisp
+
+If the multisession variable is synchronized, setting it may update
+the value. For instance:
+
+@lisp
+(incf (multisession-value foo-bar))
+@end lisp
+
+This will first check whether the value has changed in a different
+Emacs instance, retrieve that value, and then add 1 to that value, and
+then store it.
+@end defun
diff --git a/lisp/emacs-lisp/multisession.el b/lisp/emacs-lisp/multisession.el
index eb13c2e..9fefb8a 100644
--- a/lisp/emacs-lisp/multisession.el
+++ b/lisp/emacs-lisp/multisession.el
@@ -28,7 +28,7 @@
(require 'sqlite)
(defcustom multisession-database-file
- (expand-file-name "multisession.sqlite3" user-emacs-directory)
+ (expand-file-name "multisession.sqlite" user-emacs-directory)
"File to store multisession variables."
:type 'file
:version "29.1"
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- scratch/sqlite 39ca2b4: Document multisession variables,
Lars Ingebrigtsen <=