From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Stephen Berman Newsgroups: gmane.emacs.bugs Subject: bug#24923: 25.1; Lisp watchpoints Date: Sun, 20 Nov 2016 11:49:49 +0100 Message-ID: <87k2bya0j6.fsf@gmx.net> References: <87vavun235.fsf@users.sourceforge.net> <83eg2ie3lp.fsf@gnu.org> <87pom1mi3q.fsf@users.sourceforge.net> <83r36hcghy.fsf@gnu.org> <87fumwmc7q.fsf@users.sourceforge.net> <83fumvcs99.fsf@gnu.org> <874m32lx1e.fsf@users.sourceforge.net> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1479639072 17333 195.159.176.226 (20 Nov 2016 10:51:12 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 20 Nov 2016 10:51:12 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.50 (gnu/linux) Cc: 24923@debbugs.gnu.org To: npostavs@users.sourceforge.net Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Nov 20 11:51:08 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1c8PiG-0003mt-8T for geb-bug-gnu-emacs@m.gmane.org; Sun, 20 Nov 2016 11:51:08 +0100 Original-Received: from localhost ([::1]:44377 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c8PiJ-0006iS-Ps for geb-bug-gnu-emacs@m.gmane.org; Sun, 20 Nov 2016 05:51:11 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53111) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c8PiD-0006iF-I5 for bug-gnu-emacs@gnu.org; Sun, 20 Nov 2016 05:51:06 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c8PiA-0000q3-CS for bug-gnu-emacs@gnu.org; Sun, 20 Nov 2016 05:51:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:48473) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1c8PiA-0000pu-8V for bug-gnu-emacs@gnu.org; Sun, 20 Nov 2016 05:51:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1c8Pi9-00038z-Vw for bug-gnu-emacs@gnu.org; Sun, 20 Nov 2016 05:51:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Stephen Berman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 20 Nov 2016 10:51:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 24923 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 24923-submit@debbugs.gnu.org id=B24923.147963901411997 (code B ref 24923); Sun, 20 Nov 2016 10:51:01 +0000 Original-Received: (at 24923) by debbugs.gnu.org; 20 Nov 2016 10:50:14 +0000 Original-Received: from localhost ([127.0.0.1]:35639 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1c8PhN-00037P-RR for submit@debbugs.gnu.org; Sun, 20 Nov 2016 05:50:14 -0500 Original-Received: from mout.gmx.net ([212.227.15.18]:60630) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1c8PhL-000377-2v for 24923@debbugs.gnu.org; Sun, 20 Nov 2016 05:50:11 -0500 Original-Received: from rosalinde ([89.245.65.169]) by mail.gmx.com (mrgmx001 [212.227.17.190]) with ESMTPSA (Nemesis) id 0LaooK-1cb6c21c0O-00kO7e; Sun, 20 Nov 2016 11:49:50 +0100 In-Reply-To: <874m32lx1e.fsf@users.sourceforge.net> (npostavs's message of "Sat, 19 Nov 2016 21:12:13 -0500") X-Provags-ID: V03:K0:8jr+fw4n+QYpuHRtt8KwiyfobDbBay1Jct0FOe7h70jk2gJcJ+0 6Rzb6GAXd4e82NkETpatlhAYCAyktllYFyHe2mhTy4xkw2QVoB4GjPMmpJLxuLDhsCuzrPF 1fsjktwqa5GYxmFBp1ffVVPMFUscTZ5OSkHDH8epNNfPNI4s6dxEEKoa9MjUlz4yhoQmbhd ZvxDUveh/0nQe9Xr42P4A== X-UI-Out-Filterresults: notjunk:1;V01:K0:bqKzFmi6jB8=:ZX9mlTH3tV0F36LaPU7g8x Ln4SEHHd4fu1ArCUsYmIuSksfnW1aOXGewhJOaxA31VMkgrTo37TwCl+SLL64vfQ0OvsVclvj g2+XcvN0VdNs72a0MjAQ8+2zcEeDv/Fc/GZpLcB+a7My79S+PRhGTK5HBEbpkfMuIUQQYT6Q3 uPDUn3TuGTOI2QTYBhnzfRvopGhCBFNqNNLQn9eQPKO1ozKQTtm6sI/jyrgsCYbmxQg8MzP3g 4EaVMIMVLFsW3KclqHsycvxufbF7lEXpOE/w6kitw6z8D5fgKcJ9fDfC5klkW2s8sBQVOZtaw u35Vx9ndyNPMEkWYdbTOYtSDxxk+B/O2TWrBcfJ5k03cQeHpHm1nmv/z0RKA9DY4f9wUoumh/ U28TfS/tgdxUJAB8KP5gBnvZZtdqZCEiwTkPMF0UFZk2H+fUeGusupWLG9n1wlg3k2CGp0XK0 /Q6x4qTTbWOEqaQYLdc6s+w5i6MXNML31u6auggkrH0QMt9IZheMEXUbpvLpGeYbdfQZZfx1h XsH7zX3Fy1ZVsAHwTqZDNA/Vha6YkUk3R1ywtkHf/tE0Wu1Mz586YwMDXslAL/Dd+YDUZK2F0 qaLblcuRhqV54Rpr9WCOWZWt6/wUuYb8JlLG42BqprBZ3J5AL0m5ERHjH5gPLEW0Ws4HrU/kv bsM9jLOrCp+Pu7gxrPXo3aQq4TRtEm+a5QOrumI6g3OOeX+dTPeyAT3SW9I4YT8KaNchTcjnu jpvkt82qhAwcpLhSr1u9y5aqMaPLJxdtRJjKIeZDveTbKDwj5RZiBM9WK1uFbBBsiXen44ql X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:125892 Archived-At: 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 > 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 > 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 > 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