GNU bug report logs - #37875
27.0.50; `run-with-timer' not documented in (elisp)Timers

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 37875 in the body.
You can then email your comments to 37875 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: Phil Sainty <psainty <at> orcon.net.nz>
To: bug-gnu-emacs <at> gnu.org
Subject: 27.0.50; `run-with-timer' not documented in (elisp)Timers
Date: Wed, 23 Oct 2019 07:38:06 +1300

I just noticed that `run-with-timer' is not mentioned anywhere
in the elisp manual.

(elisp)Timers even mentions `run-with-idle-timer', which also has
its own node at (elisp)Idle Timers; however `run-with-timer' is
not pointed out.

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Phil Sainty <psainty <at> orcon.net.nz>
Cc: 37875 <at> debbugs.gnu.org
Subject: Re: bug#37875: 27.0.50; `run-with-timer' not documented in
 (elisp)Timers
Date: Wed, 23 Oct 2019 09:01:37 +0200

Phil Sainty <psainty <at> orcon.net.nz> writes:

> I just noticed that `run-with-timer' is not mentioned anywhere
> in the elisp manual.
>
> (elisp)Timers even mentions `run-with-idle-timer', which also has
> its own node at (elisp)Idle Timers; however `run-with-timer' is
> not pointed out.

It mentions `run-at-time' which is ... quite the same?  I share your
confusion: seems the commands `run-at-time' and `run-with-timer' can be
merged and one can be made an alias for the other.


Michael.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: Phil Sainty <psainty <at> orcon.net.nz>, 37875 <at> debbugs.gnu.org
Subject: Re: bug#37875: 27.0.50; `run-with-timer' not documented in
 (elisp)Timers
Date: Mon, 28 Oct 2019 16:55:02 +0100

Michael Heerdegen <michael_heerdegen <at> web.de> writes:

> Phil Sainty <psainty <at> orcon.net.nz> writes:
>
>> I just noticed that `run-with-timer' is not mentioned anywhere
>> in the elisp manual.
>>
>> (elisp)Timers even mentions `run-with-idle-timer', which also has
>> its own node at (elisp)Idle Timers; however `run-with-timer' is
>> not pointed out.
>
> It mentions `run-at-time' which is ... quite the same?  I share your
> confusion: seems the commands `run-at-time' and `run-with-timer' can be
> merged and one can be made an alias for the other.

The definition is:

(defun run-with-timer (secs repeat function &rest args)
[...]
  (apply 'run-at-time secs repeat function args))

So that's a kinda strange function to have?

It's used about 50 places in the in-tree code; run-at-time is used about
80 places.  run-at-time has a better name, I think, but run-with-timer
has a name that's analogous to run-with-idle-timer.

Does anybody know why run-with-timer was added?  I think we should
obsolete one or the other, and I think run-at-time has the best name.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: michael_heerdegen <at> web.de, psainty <at> orcon.net.nz, 37875 <at> debbugs.gnu.org
Subject: Re: bug#37875: 27.0.50;
 `run-with-timer' not documented in (elisp)Timers
Date: Mon, 28 Oct 2019 19:00:57 +0200

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Mon, 28 Oct 2019 16:55:02 +0100
> Cc: Phil Sainty <psainty <at> orcon.net.nz>, 37875 <at> debbugs.gnu.org
> 
> Does anybody know why run-with-timer was added?  I think we should
> obsolete one or the other, and I think run-at-time has the best name.

  $ fgrep run-with-timer lisp/ChangeLog.*
  lisp/ChangeLog.17:15268:     (desktop-auto-save-set-timer): Replace `run-with-timer' with
  lisp/ChangeLog.6:2135:       (run-with-timer): Just call run-at-time.
  lisp/ChangeLog.6:2797:       * timer.el (run-with-timer): Set repetition interval.
  lisp/ChangeLog.6:2925:       (run-with-timer): Renamed from run-after-delay.
  lisp/ChangeLog.6:2926:       (run-at-time, run-with-timer): Return the timer.

  $ fgrep run-after-delay lisp/ChangeLog.*
  lisp/ChangeLog.6:2935:       (run-after-delay): New function.

And if you look up the last match, you will see that run-after-delay
was added on the same day timer.el got rewritten using the internal
timers (before that -- oh horror! -- it worked by running an external
program which delivered a signal to Emacs when the time came).

Does that answer your question?

(I don't really understand what would we gain by obsoleting such a
popular function.)

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: michael_heerdegen <at> web.de, psainty <at> orcon.net.nz, 37875 <at> debbugs.gnu.org
Subject: Re: bug#37875: 27.0.50; `run-with-timer' not documented in
 (elisp)Timers
Date: Tue, 29 Oct 2019 12:20:38 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

> And if you look up the last match, you will see that run-after-delay
> was added on the same day timer.el got rewritten using the internal
> timers (before that -- oh horror! -- it worked by running an external
> program which delivered a signal to Emacs when the time came).

Geez.

> Does that answer your question?

Not really -- I wondered why there were two functions (run-with-timer
and run-at-time) that are identical.

> (I don't really understand what would we gain by obsoleting such a
> popular function.)

It could be made into a defalias at least -- the run-at-time doc string
is much better than the run-with-timer one.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Phil Sainty <psainty <at> orcon.net.nz>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Eli Zaretskii <eliz <at> gnu.org>
Cc: michael_heerdegen <at> web.de, 37875 <at> debbugs.gnu.org
Subject: Re: bug#37875: 27.0.50; `run-with-timer' not documented in
 (elisp)Timers
Date: Wed, 30 Oct 2019 00:34:33 +1300

On 30/10/19 12:20 AM, Lars Ingebrigtsen wrote:
> Not really -- I wondered why there were two functions (run-with-timer
> and run-at-time) that are identical.
> 
> It could be made into a defalias at least -- the run-at-time doc string
> is much better than the run-with-timer one.

I think the point is this:

(run-with-idle-timer SECS REPEAT FUNCTION &rest ARGS)
(run-with-timer      SECS REPEAT FUNCTION &rest ARGS)
(run-at-time         TIME REPEAT FUNCTION &rest ARGS)

`run-with-timer' is the non-idle analog of `run-with-idle-timer',
with a documented expectation that one passes it a number of
seconds as its first argument SECS, being the timeout to use.

So if I see either `run-with-timer' or `run-with-idle-timer' then
I know I'm looking at a timeout argument in seconds.

`run-with-time' has a different argument, TIME, which *may* be a
number of seconds (and therefore `run-with-timer' can be defined
in terms of this); but ostensibly it's a more general function.

I'd argue for keeping them both.  If anything, I'd be inclined to
add validation to `run-with-timer' to check that an integer was
passed.


-Phil

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: michael_heerdegen <at> web.de, psainty <at> orcon.net.nz, 37875 <at> debbugs.gnu.org
Subject: Re: bug#37875: 27.0.50; `run-with-timer' not documented in
 (elisp)Timers
Date: Tue, 29 Oct 2019 14:31:46 +0200

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: michael_heerdegen <at> web.de,  psainty <at> orcon.net.nz,  37875 <at> debbugs.gnu.org
> Date: Tue, 29 Oct 2019 12:20:38 +0100
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > And if you look up the last match, you will see that run-after-delay
> > was added on the same day timer.el got rewritten using the internal
> > timers (before that -- oh horror! -- it worked by running an external
> > program which delivered a signal to Emacs when the time came).
> 
> Geez.

Yeah.

> > Does that answer your question?
> 
> Not really -- I wondered why there were two functions (run-with-timer
> and run-at-time) that are identical.

Because they aren't identical, see Phil's response.  run-after-delay
was just that: it would run the function after a delay of SECS, and
that argument isn't supposed to be anything but a number of seconds to
wait from NOW.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: michael_heerdegen <at> web.de, psainty <at> orcon.net.nz, 37875 <at> debbugs.gnu.org
Subject: Re: bug#37875: 27.0.50; `run-with-timer' not documented in
 (elisp)Timers
Date: Tue, 29 Oct 2019 13:37:08 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Not really -- I wondered why there were two functions (run-with-timer
>> and run-at-time) that are identical.
>
> Because they aren't identical, see Phil's response.  run-after-delay
> was just that: it would run the function after a delay of SECS, and
> that argument isn't supposed to be anything but a number of seconds to
> wait from NOW.

I grepped through the tree -- people seem to use the two functions
interchangeably (i.e., there are calls to run-with-timer with a t value
for SECS etc).

But, OK, if you want to have two functions that are identical (only
differing in the doc string), then both functions should be documented
in the lispref manual.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: michael_heerdegen <at> web.de, psainty <at> orcon.net.nz, 37875 <at> debbugs.gnu.org
Subject: Re: bug#37875: 27.0.50; `run-with-timer' not documented in
 (elisp)Timers
Date: Tue, 29 Oct 2019 14:41:06 +0200

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: michael_heerdegen <at> web.de,  psainty <at> orcon.net.nz,  37875 <at> debbugs.gnu.org
> Date: Tue, 29 Oct 2019 13:37:08 +0100
> 
> But, OK, if you want to have two functions that are identical (only
> differing in the doc string), then both functions should be documented
> in the lispref manual.

No objections from me.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: michael_heerdegen <at> web.de, psainty <at> orcon.net.nz, 37875 <at> debbugs.gnu.org
Subject: Re: bug#37875: 27.0.50; `run-with-timer' not documented in
 (elisp)Timers
Date: Tue, 29 Oct 2019 22:22:36 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

>> But, OK, if you want to have two functions that are identical (only
>> differing in the doc string), then both functions should be documented
>> in the lispref manual.
>
> No objections from me.

OK; done.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

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