suspend-tty

suspend-tty

[Eli Zaretskii]

Does anyone know what is the purpose of suspend-tty?  (Please don't
tell "to stop I/O from/to a terminal", since that just repeats the
name of the function.)  IOW, under what circumstances would a Lisp
program want to do that, and what could be then done with the terminal
which Emacs ``suspended''?

I tried invoking suspend-tty on a GNU/Linux machine, and the terminal
just got hang, the only thing I could do is abort Emacs.  (If I had
another tty open in the same session, I understand I could resume-tty,
but that doesn't really answers my question.)  I thought suspend-tty
would leave the terminal free for use by other programs, but it sounds
like I misunderstood?

The only non-trivial user of suspend-tty is server.el, but the new
functionality that uses it is completely undocumented, both in the
code, in NEWS and in the manuals, and the semantics of using this API
evaded me.

Can someone give a hint?

TIA

Re: suspend-tty

[Stefan Monnier]

> Does anyone know what is the purpose of suspend-tty?  (Please don't
> tell "to stop I/O from/to a terminal", since that just repeats the
> name of the function.)  IOW, under what circumstances would a Lisp
> program want to do that, and what could be then done with the terminal
> which Emacs ``suspended''?

[ The blind leading the blind... ]

In the case of server.er, I believe it's used as follows:
When emacsclient receives a SIGSTOP (aka C-z), it sends a message to the
Emacs process, which then calls suspend-tty, which basically puts the
corresponding terminal object in a special state that prevents Emacs from
reading&writing to/from that tty.  Then the Emacs process sends
a message to emacsclient to suspend itself (so the shell from which it
was started is told that the suspend has taken place).

So suspend-tty just stops Emacs from using that tty (and tries to
restore its mode to default settings) so that some other application can
take control of it.

> I tried invoking suspend-tty on a GNU/Linux machine, and the terminal
> just got hang, the only thing I could do is abort Emacs.  (If I had
> another tty open in the same session, I understand I could resume-tty,
> but that doesn't really answers my question.)  I thought suspend-tty
> would leave the terminal free for use by other programs, but it sounds
> like I misunderstood?

It was probably free for use by other programs, but no other program was
told to use it.  E.g. the shell from which you started Emacs was not
told, so it was still waiting for Emacs to suspend itself or to exit.

> The only non-trivial user of suspend-tty is server.el, but the new
> functionality that uses it is completely undocumented, both in the
> code, in NEWS and in the manuals, and the semantics of using this API
> evaded me.

For me, the docstring seems to say "clearly" what the function does.
The name is slightly misleading, tho, because it applies to a terminal
rather than to a tty.  Of course, it only applies to terminals of tty
kind, but a given tty can have several terminals associated with it
(e.g. if you do "emacsclient -t; C-z; emacsclient -t").

So, do you understand what it does, now?  If so, how would you suggest
we change the docstring to make it more clear for you as well?


        Stefan

Re: suspend-tty

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Fri, 10 Oct 2008 13:15:46 -0400
> 
> In the case of server.er, I believe it's used as follows:
> When emacsclient receives a SIGSTOP (aka C-z), it sends a message to the
> Emacs process, which then calls suspend-tty, which basically puts the
> corresponding terminal object in a special state that prevents Emacs from
> reading&writing to/from that tty.  Then the Emacs process sends
> a message to emacsclient to suspend itself (so the shell from which it
> was started is told that the suspend has taken place).

And the purpose of all this jumping through the hoops is...?  If it's
just for suspending emacsclient, why isn't it enough to let the normal
SIGSTOP handler do its thing, i.e. suspend emacsclient itself? why is
there a need to suspend the Emacs terminal as well?  What am I
missing?

> It was probably free for use by other programs, but no other program was
> told to use it.

So the only way to use that terminal is for some other program to open
it for I/O?

> For me, the docstring seems to say "clearly" what the function does.

It says clearly what the function does (remember that I also read the
sources, so I knew what it does even without the doc string), but what
I was looking for was something else: who would need to call it, and
why.  IOW, I looked for a simple use-case for this API.

Re: suspend-tty

[Stefan Monnier]

>> In the case of server.er, I believe it's used as follows:
>> When emacsclient receives a SIGSTOP (aka C-z), it sends a message to the
>> Emacs process, which then calls suspend-tty, which basically puts the
>> corresponding terminal object in a special state that prevents Emacs from
>> reading&writing to/from that tty.  Then the Emacs process sends
>> a message to emacsclient to suspend itself (so the shell from which it
>> was started is told that the suspend has taken place).

> And the purpose of all this jumping through the hoops is...?  If it's
> just for suspending emacsclient, why isn't it enough to let the normal
> SIGSTOP handler do its thing, i.e. suspend emacsclient itself? why is
> there a need to suspend the Emacs terminal as well?  What am I
> missing?

Because it's the Emacs process that's using the tty, not `emacsclient'.
So, when we hit C-z, emacsclient has to tell Emacs to stop using the tty
otherwise the shell and Emacs will end up both using it at the same
time, leading to corrupted display, unusable input that sometimes goes
to one sometimes to the other process, ...

>> It was probably free for use by other programs, but no other program was
>> told to use it.
> So the only way to use that terminal is for some other program to open
> it for I/O?

Or, the shell from which Emacs was started (assuming it was started
from a shell) could use it, but you'd have to tell it that it's
available.

>> For me, the docstring seems to say "clearly" what the function does.
> It says clearly what the function does (remember that I also read the
> sources, so I knew what it does even without the doc string), but what
> I was looking for was something else: who would need to call it, and
> why.  IOW, I looked for a simple use-case for this API.

Emacsclient is the most obvious use case.  Can't think of any other.


        Stefan

Re: suspend-tty

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Fri, 10 Oct 2008 13:15:46 -0400
> 
> In the case of server.er, I believe it's used as follows:
> When emacsclient receives a SIGSTOP (aka C-z), it sends a message to the
> Emacs process, which then calls suspend-tty, which basically puts the
> corresponding terminal object in a special state that prevents Emacs from
> reading&writing to/from that tty.  Then the Emacs process sends
> a message to emacsclient to suspend itself (so the shell from which it
> was started is told that the suspend has taken place).

And the purpose of all this jumping through the hoops is...?  If it's
just for suspending emacsclient, why isn't it enough to let the normal
SIGSTOP handler do its thing, i.e. suspend emacsclient itself? why is
there a need to suspend the Emacs terminal as well?  What am I
missing?

> It was probably free for use by other programs, but no other program was
> told to use it.

So the only way to use that terminal is for some other program to open
it for I/O?

> For me, the docstring seems to say "clearly" what the function does.

It says clearly what the function does (remember that I also read the
sources, so I knew what it does even without the doc string), but what
I was looking for was something else: who would need to call it, and
why.  IOW, I looked for a simple use-case for this API.

Anyway, thanks for the explanations.