* bug#37875: 27.0.50; `run-with-timer' not documented in (elisp)Timers
@ 2019-10-22 18:38 Phil Sainty
2019-10-23 7:01 ` Michael Heerdegen
0 siblings, 1 reply; 10+ messages in thread
From: Phil Sainty @ 2019-10-22 18:38 UTC (permalink / raw)
To: 37875
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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#37875: 27.0.50; `run-with-timer' not documented in (elisp)Timers
2019-10-22 18:38 bug#37875: 27.0.50; `run-with-timer' not documented in (elisp)Timers Phil Sainty
@ 2019-10-23 7:01 ` Michael Heerdegen
2019-10-28 15:55 ` Lars Ingebrigtsen
0 siblings, 1 reply; 10+ messages in thread
From: Michael Heerdegen @ 2019-10-23 7:01 UTC (permalink / raw)
To: Phil Sainty; +Cc: 37875
Phil Sainty <psainty@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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#37875: 27.0.50; `run-with-timer' not documented in (elisp)Timers
2019-10-23 7:01 ` Michael Heerdegen
@ 2019-10-28 15:55 ` Lars Ingebrigtsen
2019-10-28 17:00 ` Eli Zaretskii
0 siblings, 1 reply; 10+ messages in thread
From: Lars Ingebrigtsen @ 2019-10-28 15:55 UTC (permalink / raw)
To: Michael Heerdegen; +Cc: Phil Sainty, 37875
Michael Heerdegen <michael_heerdegen@web.de> writes:
> Phil Sainty <psainty@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
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#37875: 27.0.50; `run-with-timer' not documented in (elisp)Timers
2019-10-28 15:55 ` Lars Ingebrigtsen
@ 2019-10-28 17:00 ` Eli Zaretskii
2019-10-29 11:20 ` Lars Ingebrigtsen
0 siblings, 1 reply; 10+ messages in thread
From: Eli Zaretskii @ 2019-10-28 17:00 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: michael_heerdegen, psainty, 37875
> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Mon, 28 Oct 2019 16:55:02 +0100
> Cc: Phil Sainty <psainty@orcon.net.nz>, 37875@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.)
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#37875: 27.0.50; `run-with-timer' not documented in (elisp)Timers
2019-10-28 17:00 ` Eli Zaretskii
@ 2019-10-29 11:20 ` Lars Ingebrigtsen
2019-10-29 11:34 ` Phil Sainty
2019-10-29 12:31 ` Eli Zaretskii
0 siblings, 2 replies; 10+ messages in thread
From: Lars Ingebrigtsen @ 2019-10-29 11:20 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: michael_heerdegen, psainty, 37875
Eli Zaretskii <eliz@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
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#37875: 27.0.50; `run-with-timer' not documented in (elisp)Timers
2019-10-29 11:20 ` Lars Ingebrigtsen
@ 2019-10-29 11:34 ` Phil Sainty
2019-10-29 12:31 ` Eli Zaretskii
1 sibling, 0 replies; 10+ messages in thread
From: Phil Sainty @ 2019-10-29 11:34 UTC (permalink / raw)
To: Lars Ingebrigtsen, Eli Zaretskii; +Cc: michael_heerdegen, 37875
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
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#37875: 27.0.50; `run-with-timer' not documented in (elisp)Timers
2019-10-29 11:20 ` Lars Ingebrigtsen
2019-10-29 11:34 ` Phil Sainty
@ 2019-10-29 12:31 ` Eli Zaretskii
2019-10-29 12:37 ` Lars Ingebrigtsen
1 sibling, 1 reply; 10+ messages in thread
From: Eli Zaretskii @ 2019-10-29 12:31 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: michael_heerdegen, psainty, 37875
> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: michael_heerdegen@web.de, psainty@orcon.net.nz, 37875@debbugs.gnu.org
> Date: Tue, 29 Oct 2019 12:20:38 +0100
>
> Eli Zaretskii <eliz@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.
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#37875: 27.0.50; `run-with-timer' not documented in (elisp)Timers
2019-10-29 12:31 ` Eli Zaretskii
@ 2019-10-29 12:37 ` Lars Ingebrigtsen
2019-10-29 12:41 ` Eli Zaretskii
0 siblings, 1 reply; 10+ messages in thread
From: Lars Ingebrigtsen @ 2019-10-29 12:37 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: michael_heerdegen, psainty, 37875
Eli Zaretskii <eliz@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
^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#37875: 27.0.50; `run-with-timer' not documented in (elisp)Timers
2019-10-29 12:37 ` Lars Ingebrigtsen
@ 2019-10-29 12:41 ` Eli Zaretskii
2019-10-29 21:22 ` Lars Ingebrigtsen
0 siblings, 1 reply; 10+ messages in thread
From: Eli Zaretskii @ 2019-10-29 12:41 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: michael_heerdegen, psainty, 37875
> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: michael_heerdegen@web.de, psainty@orcon.net.nz, 37875@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.
^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2019-10-29 21:22 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-10-22 18:38 bug#37875: 27.0.50; `run-with-timer' not documented in (elisp)Timers Phil Sainty
2019-10-23 7:01 ` Michael Heerdegen
2019-10-28 15:55 ` Lars Ingebrigtsen
2019-10-28 17:00 ` Eli Zaretskii
2019-10-29 11:20 ` Lars Ingebrigtsen
2019-10-29 11:34 ` Phil Sainty
2019-10-29 12:31 ` Eli Zaretskii
2019-10-29 12:37 ` Lars Ingebrigtsen
2019-10-29 12:41 ` Eli Zaretskii
2019-10-29 21:22 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).