bug#30461: 27.0.50; Incorrect description of sentinels

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed, 14 Feb 2018 23:10:32 +0100
> From: p.stephani2@gmail.com
> 
> > A =E2=80=9Cprocess sentinel=E2=80=9D is a function that is called wheneve=
> r the
> > associated process changes status for any reason, including signals
> > (whether sent by Emacs or caused by the process=E2=80=99s own actions) th=
> at
> > terminate, stop, or continue the process.
> 
> But that doesn't seem to be the case:
> 
> (let ((p (make-process :name "sleep"
> 		       :command '("sleep" "1h")
> 		       :sentinel (lambda (p s)
> 				   (message "sentinel: %S" s)))))
>    (sit-for 0.1)
>    (stop-process p)
>    (sit-for 0.1)
>    (continue-process p))
> 
> If you then check the messages buffer, you see only the following:
> 
> > sentinel: "run"
> 
> That is, the sentinel isn't called when the process is stopped or
> continued.

I think the sentinel is in fact called when the process is continued:
that's where that "run" came from, right?  You will see in
process_send_signal that we explicitly call the sentinel when the
signal is SIGCONT.

> However, the sentinel *is* called when manually sending a STOP
> signal to the process.

Did you send SIGSTOP or SIGTSTP?  stop-process sends the latter.

> Furthermore, the description about the possible event strings doesn't
> mention "run".

The documentation describes the strings produced by status_message.
You will see that there's an "else" catch-all clause there that
produces the name of the status symbol it is passed as an argument, in
case it doesn't recognize it.  I believe that's where "run" comes from
(note that it has no final newline, unlike the documented event
strings).  We could add "run", but it should be clear that by the same
token the string could be _anything_, a name of any symbol which is
stashed in the process's status.