bug#23929: 25.0.95; Doc of run-at-time doesn't describe behaviour if system was sleeping at time

[N. Jackson]

At 19:56 +0300 on Saturday 2016-07-09, Eli Zaretskii wrote:

>> From: nljlistbox2@gmail.com (N. Jackson)
>> Date: Sat, 09 Jul 2016 12:30:42 -0300
>> 
>> The documentation of run-at-time -- the doc string and (info "(elisp)
>> Timers") -- does not say what happens if the system was sleeping when
>> the timer would have run.
>
> It also doesn't say what happens if Emacs didn't get any CPU time when
> the timer would have run -- which is a more general description of the
> situation you mention.
>
> If instead
>
>   Perform an action at time TIME.
>
> we say
>
>   Perform an action at or after time TIME.
>
> will this take care of the issue you are raising?

Yes, I think it might take care of the issue.

On the other hand, perhaps it would be worth being slightly more
explicit in the documentation in the manual? Perhaps it would be
worth mentioning the general case of Emacs not getting any CPU
time when the timer would have run, as well as the specific case
of the system being suspended / sleeping.

I'm not in a good position to judge how much insight into system
internals the reader of the elisp manual is expected to have. To
me, at least, it isn't immediately obvious that the case of the
system being suspended when the timer would have run is the "same"
as the case of the system being busy elsewhere when the timer
would have run.

As a casual user of the function, I just want to know whether, if
I have a timer set to run at 6:00 AM but I don't wake up my system
until 8:00 AM, if my timer will run once my system has woken up,
or if the timer will be skipped until the next day (provided my
system is awake at 6:00 AM the next day).

I would be more reassured if I saw text along the following lines
in the manual entry (provided it is true):

    "If Emacs didn't get any CPU time when the timer would have
    run (for example if the system was busy running another
    process or if the computer was sleeping or in a suspended
    state), the timer will run (late) as soon as Emacs resumes and
    is idle."

Of course, this is already almost, but not quite, stated already
twice in the manual entry. Firstly in the second paragraph:

    "Emacs cannot run timers at any arbitrary point in a Lisp
    program; it can run them only when Emacs could accept output
    from a subprocess: namely, while waiting or inside certain
    primitive functions such as ‘sit-for’ or ‘read-event’ which
    _can_ wait. Therefore, a timer’s execution may be delayed if
    Emacs is busy. However, the time of execution is very precise
    if Emacs is idle."

But this only covers the case of Emacs being busy when the timer
would have run.

And later:

    "A repeating timer nominally ought to run every REPEAT
    seconds, but remember that any invocation of a timer can be
    late. Lateness of one repetition has no effect on the
    scheduled time of the next repetition. For instance, if Emacs
    is busy computing for long enough to cover three scheduled
    repetitions of the timer, and then starts to wait, it will
    immediately call the timer function three times in immediate
    succession (presuming no other timers trigger before or
    between them)."

But this only covers the case of repeating timers.