From: Stephen Berman <stephen.berman@gmx.net>
To: npostavs@users.sourceforge.net
Cc: 24923@debbugs.gnu.org
Subject: bug#24923: 25.1; Lisp watchpoints
Date: Sun, 20 Nov 2016 11:49:49 +0100 [thread overview]
Message-ID: <87k2bya0j6.fsf@gmx.net> (raw)
In-Reply-To: <874m32lx1e.fsf@users.sourceforge.net> (npostavs's message of "Sat, 19 Nov 2016 21:12:13 -0500")
There are a few typos in the documentation:
On Sat, 19 Nov 2016 21:12:13 -0500 npostavs@users.sourceforge.net wrote:
> From c318be2dc401d2f3b958ceb3b48e466a3019091e Mon Sep 17 00:00:00 2001
> From: Noam Postavsky <npostavs@gmail.com>
> Date: Thu, 19 Nov 2015 19:50:06 -0500
> Subject: [PATCH v6 1/6] Add lisp watchpoints
>
> This allows to call a function whenever a symbol-value is changed.
^^^^^^^
calling
> From 5d87668684319bb165ed0f31f637c44cda5716a6 Mon Sep 17 00:00:00 2001
> From: Noam Postavsky <npostavs@gmail.com>
> Date: Sat, 21 Nov 2015 17:02:42 -0500
> Subject: [PATCH v6 4/6] Ensure redisplay using variable watcher
>
> Instead of looking up the variable name in redisplay--variables when
> setting.
Incomplete sentence? Or if it's the continuation of the Subject: line,
shouldn't it be lowercase?
> From 984109b9b204c82ce2e6482210425a70b7b7e867 Mon Sep 17 00:00:00 2001
> From: Noam Postavsky <npostavs@gmail.com>
> Date: Sun, 13 Dec 2015 14:47:58 -0500
> Subject: [PATCH v6 6/6] Document watchpoints
>
> * doc/lispref/debugging.texi (Variable Debugging):
> * doc/lispref/variables.texi (Watching Variables): New section.
> * etc/NEWS: Add entry for watchpoints
> ---
> doc/lispref/debugging.texi | 32 +++++++++++++++++++++++
> doc/lispref/variables.texi | 63 ++++++++++++++++++++++++++++++++++++++++++++++
> etc/NEWS | 5 ++++
> src/data.c | 9 +++++++
> 4 files changed, 109 insertions(+)
>
> diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
> index 6c0908a..8cae203 100644
> --- a/doc/lispref/debugging.texi
> +++ b/doc/lispref/debugging.texi
[...]
> @@ -290,6 +291,37 @@ Function Debugging
> not currently set up to break on entry.
> @end deffn
>
> +@node Variable Debugging
> +@subsection Entering the debugger when a variable is modified
> +@cindex variable write debugging
> +@cindex debugging changes to variables
> +
> +Sometimes a problem with a function is due to a wrong setting of a
> +variable. Setting up the debugger to trigger whenever the variable is
> +changed is quick way to find the origin of the setting.
^
a
> +
> +@deffn Command debug-on-variable-change variable
> +This function arranges causes the debugger to be called whenever
^^^^^^^^^^^^^^^
either "arranges for" or "causes"
> diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
> index 418a416..07f787c 100644
> --- a/doc/lispref/variables.texi
> +++ b/doc/lispref/variables.texi
[...]
> @@ -765,6 +766,68 @@ Setting Variables
> @end example
> @end defun
>
> +@node Watching Variables
> +@section Running a function when a variable is changed.
> +@cindex variable watchpoints
> +
> +It is sometimes useful to take some action when a variable changes its
> +value. The watchpoint facility provides the means to do so. Some
> +possible uses for this feature include keeping display in sync with
> +variable settings, and invoking the debugger to track down unexpected
> +changes to variables @pxref{Variable Debugging}.
> +
> +Each variable has a list of watch functions stored in its
> +@code{watchers} symbol property, @xref{Symbol Properties}. However,
> +for efficiency reasons, the list is only consulted if symbol is marked
^
the
> +as watched. Therefore, the watch function list should only be
> +manipulated by the following functions, which take care of the
> +symbol's watched status in addition to the property value.
> +
> +@defun add-variable-watcher symbol watch-function
> +This function arranges for @var{watch-function} to be called whenever
> +@var{symbol} (or any of its aliases @pxref{Variable Aliases}) are
> +modified.
> +
> +It will be called with 4 arguments: (@var{symbol} @var{newval}
> +@var{operation} @var{where}).
> +
> +@var{symbol} is the variable being changed.
> +@var{newval} is the value it will be changed to.
> +@var{operation} is a symbol representing the kind of change, one of:
> +`set', `let', `unlet', `makunbound', and `defvaralias'.
> +@var{where} is a buffer if the buffer-local value of the variable
^
is
> +being changed, nil otherwise.
> +@end defun
> +
> +@defun remove-variable-watch symbol watch-function
> +This function removes @var{watch-function} from @var{symbol}'s list of
> +watchers.
> +@end defun
> +
> +@defun get-variable-watchers symbol
> +This function returns the list of active watcher functions.
> +@end defun
> +
> +@subsection Limitations
> +
> +There are a couple of ways in which a variable could be modifed (or at
> +least appear to be modified) without triggering a watchpoint.
> +
> +Since the watchpoint are attached to symbols, modification to the
^^^^^^^^^^^^^^
watchpoints
> +objects contained within variables (e.g., by a list modification
> +function @pxref{Modifying Lists}) is not caught by this mechanism.
> +
> +Additionally, C code can modify the value of variables directly,
> +bypassing the watchpoint mechanism.
> +
> +A minor limitation of this feature, again because it targets symbols,
> +is that only variables of dynamic scope may be watched. This poses
> +little difficulty, since modifications to lexical variables can be
> +discovered easily by inspecting the code within the scope of the
> +variable (unlike dynamic variables which can be modified by any code
^
, [comma]
> +at all, @pxref{Variable Scoping}).
> +
> +
> @node Variable Scoping
> @section Scoping Rules for Variable Bindings
> @cindex scoping rule
[...]
> diff --git a/src/data.c b/src/data.c
> index ff35315..ef6b48b 100644
> --- a/src/data.c
> +++ b/src/data.c
> @@ -1428,6 +1428,15 @@ harmonize_variable_watchers (Lisp_Object alias, Lisp_Object base_variable)
> DEFUN ("add-variable-watcher", Fadd_variable_watcher, Sadd_variable_watcher,
> 2, 2, 0,
> doc: /* Cause WATCH-FUNCTION to be called when SYMBOL is set.
> +
> +It will be called with 4 arguments: (SYMBOL NEWVAL OPERATION WHERE).
> +SYMBOL is the variable being changed.
> +NEWVAL is the value it will be changed to.
> +OPERATION is a symbol representing the kind of change, one of: `set',
> +`let', `unlet', `makunbound', and `defvaralias'.
> +WHERE is a buffer if the buffer-local value of the variable being
^
is
> +changed, nil otherwise.
> +
> All writes to aliases of SYMBOL will call WATCH-FUNCTION too. */)
> (Lisp_Object symbol, Lisp_Object watch_function)
> {
Steve Berman
next prev parent reply other threads:[~2016-11-20 10:49 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-11-11 3:10 bug#24923: 25.1; Lisp watchpoints npostavs
2016-11-11 10:02 ` Eli Zaretskii
2016-11-12 4:34 ` npostavs
2016-11-12 7:19 ` Eli Zaretskii
2016-11-13 0:54 ` npostavs
2016-11-13 15:29 ` Eli Zaretskii
2016-11-20 2:12 ` npostavs
2016-11-20 10:49 ` Stephen Berman [this message]
2016-11-20 14:14 ` npostavs
2016-11-20 16:11 ` Eli Zaretskii
2016-11-20 19:26 ` npostavs
2016-11-20 19:36 ` Eli Zaretskii
2016-11-20 20:16 ` npostavs
2016-11-21 17:31 ` Eli Zaretskii
2016-12-03 1:47 ` npostavs
2016-12-03 3:49 ` Clément Pit--Claudel
2016-12-03 3:50 ` Clément Pit--Claudel
2016-12-03 5:01 ` Daniel Colascione
2016-12-03 14:11 ` npostavs
2016-11-20 15:58 ` Eli Zaretskii
2016-11-20 17:00 ` npostavs
2016-11-20 17:25 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87k2bya0j6.fsf@gmx.net \
--to=stephen.berman@gmx.net \
--cc=24923@debbugs.gnu.org \
--cc=npostavs@users.sourceforge.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).