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

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

[ndame]

[-- Attachment #1: Type: text/plain, Size: 272 bytes --]

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.

[-- Attachment #2: Type: text/html, Size: 313 bytes --]

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

[Eli Zaretskii]

> Date: Tue, 18 Feb 2020 17:54:28 +0000 (GMT)
> From: ndame <emacsuser@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.

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

[ndame]

[-- Attachment #1: Type: text/plain, Size: 517 bytes --]

> 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.

[-- Attachment #2: Type: text/html, Size: 587 bytes --]

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

[Eli Zaretskii]

> Date: Tue, 18 Feb 2020 18:45:56 +0000 (GMT)
> From: ndame <emacsuser@freemail.hu>
> Cc: "39668@debbugs.gnu.org" <39668@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?

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

[ndame]

[-- Attachment #1: Type: text/plain, Size: 543 bytes --]

 
> 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.

 

[-- Attachment #2: Type: text/html, Size: 640 bytes --]

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

[Eli Zaretskii]

> Date: Tue, 18 Feb 2020 19:36:08 +0000 (GMT)
> From: ndame <emacsuser@freemail.hu>
> Cc: "39668@debbugs.gnu.org" <39668@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.

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

[ndame]

[-- Attachment #1: Type: text/plain, Size: 335 bytes --]

 
> 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.

[-- Attachment #2: Type: text/html, Size: 385 bytes --]