From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: npostavs@users.sourceforge.net Newsgroups: gmane.emacs.bugs Subject: bug#24923: 25.1; Lisp watchpoints Date: Sun, 20 Nov 2016 09:14:02 -0500 Message-ID: <87wpfyjl1x.fsf@users.sourceforge.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> <87k2bya0j6.fsf@gmx.net> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: blaine.gmane.org 1479651268 16958 195.159.176.226 (20 Nov 2016 14:14:28 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 20 Nov 2016 14:14:28 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux) Cc: 24923@debbugs.gnu.org To: Stephen Berman Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Nov 20 15:14:24 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 1c8Ssx-0003eU-Vz for geb-bug-gnu-emacs@m.gmane.org; Sun, 20 Nov 2016 15:14:24 +0100 Original-Received: from localhost ([::1]:45071 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c8St1-0002oe-II for geb-bug-gnu-emacs@m.gmane.org; Sun, 20 Nov 2016 09:14:27 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:55066) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c8Ssf-0002fZ-90 for bug-gnu-emacs@gnu.org; Sun, 20 Nov 2016 09:14:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c8Ssc-0000zO-1E for bug-gnu-emacs@gnu.org; Sun, 20 Nov 2016 09:14:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:48566) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1c8Ssb-0000zG-Tj for bug-gnu-emacs@gnu.org; Sun, 20 Nov 2016 09:14:01 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1c8Ssb-0001oL-JO for bug-gnu-emacs@gnu.org; Sun, 20 Nov 2016 09:14:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: npostavs@users.sourceforge.net Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 20 Nov 2016 14:14: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.14796511986889 (code B ref 24923); Sun, 20 Nov 2016 14:14:01 +0000 Original-Received: (at 24923) by debbugs.gnu.org; 20 Nov 2016 14:13:18 +0000 Original-Received: from localhost ([127.0.0.1]:35732 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1c8Sru-0001n1-Bp for submit@debbugs.gnu.org; Sun, 20 Nov 2016 09:13:18 -0500 Original-Received: from mail-io0-f182.google.com ([209.85.223.182]:34300) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1c8Srt-0001mp-Ah for 24923@debbugs.gnu.org; Sun, 20 Nov 2016 09:13:17 -0500 Original-Received: by mail-io0-f182.google.com with SMTP id c21so20957307ioj.1 for <24923@debbugs.gnu.org>; Sun, 20 Nov 2016 06:13:17 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=ozRylucf2FKV6X5dZcR9k+35ASX2SUUHfeI38uVNAMY=; b=HJp5vcFVgdeUWiT3gzk/+ily3lV0BC752y1xxSF1v2l90sfAVcWyXrH/z6syU2EjeY Ei3BBqGABnHSdcCawRdX2pS8cwnfTMqbLcFMvFARuZCwo9X9r17tAO/iJXTVhbhg8Mxl nQpiTgHADfhF9VVVDjqeDQ6xd//gTmVGfr8QriAU09+/7ERxANMtxrVcn+ttyFUMBDGS 4uQTYqUPlA0EUVPRxZ1UgvVRmEtxyQSPHU6/zyOJsoe8uFa2pC9xe9oH7F9qIj58HsLr BzqC4rqEo7jFExqYQMY0YO4KP+VE1DVC6jlzhp3wFjSE8DZ/kSPV9K+KSZx1BRFo41Bc ClQA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:sender:from:to:cc:subject:references:date :in-reply-to:message-id:user-agent:mime-version; bh=ozRylucf2FKV6X5dZcR9k+35ASX2SUUHfeI38uVNAMY=; b=LwABDv4US8wM9G+/0Dki0glcOBj7BpHwvWnxDycWNJUph62hzzSgaDfEu7GJYirx0M dwp42nhDZBr5Cs3QAJjXFRjM1zTtEGRkGqswg4f4tHNz2mh1iwKZdbqXxHXKgPTZgApW 1zJuYAe34tRCmRjiIyEc4CFamFUOWMd/88nEtN72SkFHrw/NtXY/vkhloEh8FSmo5U8k sNSy2NMtsQpmcxsSQ2/sI4YmO/oD+ShtyApm69Am8OnEh78/ZqrFsW+UXCrGOfFXZQ+O B/yFigTtLNRoscGgA8FQ4UN2IpTck/2T4NIDcZH8UsPSyytWvdT5eY1EbRaK9wPGnVhU Af1g== X-Gm-Message-State: AKaTC02LcErA6aVqIoGKdDd0ijvjzJnCIjnMkkQYEiYlspd4USo6AMt55WFUa1E+kRoKiA== X-Received: by 10.107.48.134 with SMTP id w128mr9179781iow.226.1479651191493; Sun, 20 Nov 2016 06:13:11 -0800 (PST) Original-Received: from zony ([45.2.7.65]) by smtp.googlemail.com with ESMTPSA id l14sm6415359ioi.18.2016.11.20.06.13.10 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Sun, 20 Nov 2016 06:13:10 -0800 (PST) In-Reply-To: <87k2bya0j6.fsf@gmx.net> (Stephen Berman's message of "Sun, 20 Nov 2016 11:49:49 +0100") 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:125897 Archived-At: --=-=-= Content-Type: text/plain Stephen Berman writes: > There are a few typos in the documentation: Thanks, reattaching just the fixed documentation commit. --=-=-= Content-Type: text/plain Content-Disposition: attachment; filename=v6.1-0006-Document-watchpoints.patch Content-Description: patch >From b2aff88d97942c32fb0e2695e47ad2cb3433c71f Mon Sep 17 00:00:00 2001 From: Noam Postavsky Date: Sun, 13 Dec 2015 14:47:58 -0500 Subject: [PATCH v6.1 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..c047d45 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -69,6 +69,7 @@ Debugger * Error Debugging:: Entering the debugger when an error happens. * Infinite Loops:: Stopping and debugging a program that doesn't exit. * Function Debugging:: Entering it when a certain function is called. +* Variable Debugging:: Entering it when a variable is modified. * Explicit Debug:: Entering it at a certain point in the program. * Using Debugger:: What the debugger does; what you see while in it. * Debugger Commands:: Commands used while in the debugger. @@ -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 a quick way to find the origin of the setting. + +@deffn Command debug-on-variable-change variable +This function arranges for the debugger to be called whenever +@var{variable} is modified. + +It is implemented using the watchpoint mechanism, so it inherits the +same characteristics and limitations: all aliases of @var{variable} +will be watched together, only dynamic variables can be watched, and +changes to the objects referenced by variables are not detected. For +details, see @xref{Watching Variables}. + +@end deffn + +@deffn Command cancel-debug-on-variable-change &optional variable +This function undoes the effect of @code{debug-on-variable-change} on +@var{variable}. When called interactively, it prompts for +@var{variable} in the minibuffer. If @var{variable} is omitted or +@code{nil}, it cancels break-on-change for all variables. Calling +@code{cancel-debug-on-variable-change} does nothing to a variable +which is not currently set up to break on change. +@end deffn + + @node Explicit Debug @subsection Explicit Entry to the Debugger @cindex debugger, explicit entry diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 418a416..1e0b098 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -34,6 +34,7 @@ Variables * Accessing Variables:: Examining values of variables whose names are known only at run time. * Setting Variables:: Storing new values in variables. +* Watching Variables:: Running a function when a variable is changed. * Variable Scoping:: How Lisp chooses among local and global values. * Buffer-Local Variables:: Variable values in effect only in one buffer. * File Local Variables:: Handling local variable lists in files. @@ -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 the symbol is +marked 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 watchpoints are attached to symbols, modification to the +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 +at all, @pxref{Variable Scoping}). + + @node Variable Scoping @section Scoping Rules for Variable Bindings @cindex scoping rule diff --git a/etc/NEWS b/etc/NEWS index e29dfe2..fcbbb44 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -627,6 +627,11 @@ consistency with the new functions. For compatibility, 'sxhash' remains as an alias to 'sxhash-equal'. +++ +** New function `add-variable-watcher' can be used to call a function +when a symbol's value is changed. This is used to implement the new +debugger command `debug-on-variable-change'. + ++++ ** Time conversion functions that accept a time zone rule argument now allow it to be OFFSET or a list (OFFSET ABBR), where the integer OFFSET is a count of seconds east of Universal Time, and the string 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 +changed, nil otherwise. + All writes to aliases of SYMBOL will call WATCH-FUNCTION too. */) (Lisp_Object symbol, Lisp_Object watch_function) { -- 2.9.3 --=-=-= Content-Type: text/plain > >> 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? I sort of about it as a continuation, but it looks a bit weird to make it an official continuation when there's a blank line in between. I rephrased: This replaces checking for the variable name in redisplay--variables when setting it. --=-=-=--