GNU bug report logs - #39668
26.2; timer-list and timer-idle-list are undocumented in the Elisp manual

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 39668 in the body.
You can then email your comments to 39668 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: ndame <emacsuser <at> freemail.hu>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 26.2; timer-list and timer-idle-list are undocumented in the Elisp
 manual
Date: Tue, 18 Feb 2020 17:54:28 +0000 (GMT)

[Message part 1 (text/plain, inline)]

I checked under Timers for Delayed Execution, but there was no 
info there how to get the list of active timers.

It mentions the list-timers command, but not the above variables,
so I had to check the source code of list-timers to find out about
these variables.

[Message part 2 (text/html, inline)]

Message #8 received at 39668 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: ndame <emacsuser <at> freemail.hu>
Cc: 39668 <at> debbugs.gnu.org
Subject: Re: bug#39668: 26.2;
 timer-list and timer-idle-list are undocumented in the Elisp manual
Date: Tue, 18 Feb 2020 20:35:15 +0200

> Date: Tue, 18 Feb 2020 17:54:28 +0000 (GMT)
> From: ndame <emacsuser <at> freemail.hu>
> 
> I checked under Timers for Delayed Execution, but there was no 
> info there how to get the list of active timers.
> 
> It mentions the list-timers command, but not the above variables,
> so I had to check the source code of list-timers to find out about
> these variables.

And what is wrong with that, may I ask?

These variables are internal implementation details of how timers work
in Emacs.  The ELisp manual documents the facilities available for
Lisp programs, it doesn't document how each facility is implemented --
for that, you indeed need to read the sources.

Message #11 received at 39668 <at> debbugs.gnu.org (full text, mbox):

From: ndame <emacsuser <at> freemail.hu>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "39668 <at> debbugs.gnu.org" <39668 <at> debbugs.gnu.org>
Subject: Re: bug#39668: 26.2; timer-list and timer-idle-list are
 undocumented in the Elisp manual
Date: Tue, 18 Feb 2020 18:45:56 +0000 (GMT)

[Message part 1 (text/plain, inline)]

> These variables are internal implementation details of how timers work
> in Emacs. The ELisp manual documents the facilities available for
> Lisp programs,

I needed to access the list of the active timers from an elisp program. 
Since timers are available from elisp, the list of timers should be 
available too, like the list of buffers, etc.

I was suprised that I did not find this in the manual. Since timers are
part of the public elisp api, I expect timer lists also to be part of the
public api.

[Message part 2 (text/html, inline)]

Message #14 received at 39668 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: ndame <emacsuser <at> freemail.hu>
Cc: 39668 <at> debbugs.gnu.org
Subject: Re: bug#39668: 26.2; timer-list and timer-idle-list are
 undocumented in the Elisp manual
Date: Tue, 18 Feb 2020 21:26:12 +0200

> Date: Tue, 18 Feb 2020 18:45:56 +0000 (GMT)
> From: ndame <emacsuser <at> freemail.hu>
> Cc: "39668 <at> debbugs.gnu.org" <39668 <at> debbugs.gnu.org>
> 
> I needed to access the list of the active timers from an elisp program. 
> Since timers are available from elisp, the list of timers should be 
> available too, like the list of buffers, etc.
> 
> I was suprised that I did not find this in the manual. Since timers are
> part of the public elisp api, I expect timer lists also to be part of the
> public api.

We don't describe those lists intentionally, because messing with them
can produce unexpected results.  Think about that: while you are
modifying the list of timers, some timer might expire, and Emacs will
run it, and modify the list as result.  (We do have protection from at
least the simplest forms of such races, but still, we don't like to
have Lisp programs manipulate those lists.)

Why do you need to access the active timers?

Message #17 received at 39668 <at> debbugs.gnu.org (full text, mbox):

From: ndame <emacsuser <at> freemail.hu>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "39668 <at> debbugs.gnu.org" <39668 <at> debbugs.gnu.org>
Subject: Re: bug#39668: 26.2; timer-list and timer-idle-list are
 undocumented in the Elisp manual
Date: Tue, 18 Feb 2020 19:36:08 +0000 (GMT)

[Message part 1 (text/plain, inline)]

 
> Why do you need to access the active timers?

I wanted only to check the existing timers, not modify them,
so I needed only read only access. I don't modify anything.

I use this to avoid starting a timer if one is started already. So I just
check the timer list for the function names if it already contains 
my function. If so then I don't start a timer, because it's already done.

So the timer list eliminates the need of me haveing to store the timer in a variable,
because the list tells me if it's already active.

 

[Message part 2 (text/html, inline)]

Message #20 received at 39668 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: ndame <emacsuser <at> freemail.hu>
Cc: 39668 <at> debbugs.gnu.org
Subject: Re: bug#39668: 26.2; timer-list and timer-idle-list are
 undocumented in the Elisp manual
Date: Tue, 18 Feb 2020 21:57:51 +0200

> Date: Tue, 18 Feb 2020 19:36:08 +0000 (GMT)
> From: ndame <emacsuser <at> freemail.hu>
> Cc: "39668 <at> debbugs.gnu.org" <39668 <at> debbugs.gnu.org>
> 
> > Why do you need to access the active timers?
> 
> I wanted only to check the existing timers, not modify them,
> so I needed only read only access. I don't modify anything.
> 
> I use this to avoid starting a timer if one is started already. So I just
> check the timer list for the function names if it already contains 
> my function. If so then I don't start a timer, because it's already done.
> 
> So the timer list eliminates the need of me haveing to store the timer in a variable,
> because the list tells me if it's already active.

There are other ways of doing that, but if you really need it for such
a rare use case, there's nothing wrong in reading the code.

Message #23 received at 39668 <at> debbugs.gnu.org (full text, mbox):

From: ndame <emacsuser <at> freemail.hu>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "39668 <at> debbugs.gnu.org" <39668 <at> debbugs.gnu.org>
Subject: Re: bug#39668: 26.2; timer-list and timer-idle-list are
 undocumented in the Elisp manual
Date: Tue, 18 Feb 2020 20:04:21 +0000 (GMT)

[Message part 1 (text/plain, inline)]

 
> There are other ways of doing that, but if you really need it for such
> a rare use case, there's nothing wrong in reading the code.

OK, I only opened this bug, because I though it was an oversight in the manual,
but if it's intentional, and the list is not considered as part of the public api then
this bug can be closed.

[Message part 2 (text/html, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.