question about `sit-for' and `C-g'

question about `sit-for' and `C-g'

[Drew Adams]

I have some code that, during minibuffer completion, sometimes shows something
in the mode line for a `sit-for' period (user-configurable).  `sit-for' calls
`read-event' and, except for prefix-arg keys, supposedly pushes the input event
back onto `unread-command-events'.

If the user hits `C-g' during the `sit-for' period, then, instead of the `C-g'
binding in effect in the minibuffer being respected, it seems like
`sit-for'/`read-event' handles the `C-g' event directly (?). 

The effect, in any case, seems to be this: (a) `ding' (the bell rings, with the
message `Quit') and (b) the `C-g' gets lost/ignored, so the user needs to hit
`C-g' again to get the normal minibuffer `C-g' behavior.  AFAICT, there is no
actual quit effected - no SIGQUIT, but there are its indications: bell, message.
Certainly, the `C-g' binding in effect in the minibuffer is ignored.

Dunno whether the `C-g' event is ignored/lost, or it is (mis)handled only by
dinging and saying `Quit'.  It shouldn't be ignored/lost, since the `sit-for'
code apparently pushes it to `unread-command-events'.  It's not clear to me just
what is happening, but I'm sure that something other than my code (directly, at
least) is ringing the bell and writing `Quit'.

I have only the Emacs 23.3 C code, but it is perhaps the same for Emacs 24
`read-event' etc.  That function calls `read_filtered_event', and I don't see
anything in that function that handles `C-g' specially.

Except that `read_filtered_event' calls `read_char', which does seem to do
something wrt the quit char (C-g), at least in some cases.  It's not clear to me
just what it does, but if I had to guess it would be that this might be where
the `C-g' is ringing the bell and getting swallowed up.

I'm no expert when it comes to C code, clearly.  Perhaps someone can clue me in.
What am I missing?  What is handling this C-g during `sit-for'?  And should it
be?  Should `sit-for' handle `C-g' its own way, ignoring any `C-g' binding?  (I
understand that `read-event' should do so, but I wonder about `sit-for'.)

Anyway, besides helping me understand what's happening, what's the best way to
get the `C-g' here handled normally (i.e., as a `C-g' in the minibuffer
keymaps)?  I guess I could call a substitute for `sit-for' that tests the
char/event read and explicitly DTRT for `C-g'.  Is that what you would
recommend, or should `sit-for' itself perhaps do something different/better?
(`sit-for' already handles prefix-arg keys specially.)

If I had to guess, after reading this over, it would be that you'll say that
`sit-for', like `read-event', should not itself handle `C-g' in the normal way
(i.e., pass it along, respecting its current key binding), and that it should,
like `read-event', treat `C-g' in a hard-coded way.  I'd still like to hear
about this (explanation, reasons, etc.), so I can understand better.

Thx.

RE: question about `sit-for' and `C-g'

[Drew Adams]

Let me just add that the doc of none of the functions I mentioned, whether Lisp
or C, mentions anything about handling quitting, the quit character, or C-g.

So if, as it appears to me, C function `read_char' handles C-g directly, this is
not documented for that function nor for any of the multiple functions that call
it, directly or indirectly.  This doesn't seem right.

RE: question about `sit-for' and `C-g'

[Drew Adams]

It seems that all I had to do was define a substitute for `sit-for' that does
exactly the same thing but also binds `inhibit-quit' to t around the call to
`read-event'.

I'm still interested in the questions I posed and learning more about this.

My next question is whether `sit-for' itself should do the same thing: bind
`inhibit-quit' to t.

RE: question about `sit-for' and `C-g'

[Herring, Davis]

> It seems that all I had to do was define a substitute for `sit-for' that does
> exactly the same thing but also binds `inhibit-quit' to t around the call to
> `read-event'.

Or you can just do that binding around your call to `sit-for'.

> I'm still interested in the questions I posed and learning more about this.

At top level, C-g is bound to `keyboard-quit'.  In the minibuffer, it's typically bound to `abort-recursive-edit' (since reading from the minibuffer is a special, unadvertised kind of recursive edit).  Much more important, though, is that while not in a command loop (e.g., during `sit-for'), `quit-char' is turned directly into a `quit' signal (not SIGQUIT; that's an unrelated Unix concept).  That signal unwinds the call stack until it hits a recursive editing level (which catches all exceptions) and prints "Quit".

From a conceptual if not a C-implementation point of view, then, `read-char' and so forth do not handle C-g in any special way.  That is to say, it does what it always does, and aborts the currently running Lisp code.  As it is global and standard, they do not document that behavior; see (elisp)Quitting.

> My next question is whether `sit-for' itself should do the same thing: bind
> `inhibit-quit' to t.

Surely not.  Aborting a command like yours in a normal minibuffer would then abort the whole minibuffer (because you'd get C-g in `unread-command-events' AND the `quit' signal).  And while it's easy to add a let-binding to get the behavior you want, you couldn't ever go back were it the default.

Davis

RE: question about `sit-for' and `C-g'

[Drew Adams]

> > It seems that all I had to do was define a substitute for 
> > `sit-for' that does exactly the same thing but also binds
> > `inhibit-quit' to t around the call to `read-event'.
> 
> Or you can just do that binding around your call to `sit-for'.

Of course.

[But I already use a substitute for `sit-for' in Icicle mode, which checks
`overriding-terminal-local-map' against `icicle-universal-argument-map', in
addition to `universal-argument-map'.  (The commands in the former map echo the
prefix arg, which can be used separately for individual completion candidates.)

And I do want `C-g' to be handled by its current keybinding for each call to
`sit-for' in my code.  For both of these reasons it makes sense to bind
`inhibit-quit' in `icicle-sit-for'.]

> At top level, C-g is bound to `keyboard-quit'.  In the 
> minibuffer, it's typically bound to `abort-recursive-edit' 
> (since reading from the minibuffer is a special, unadvertised 
> kind of recursive edit).

Yes, but neither of those is involved here.  In fact, there is _no_ key binding
of `C-g' that is involved.

And searching Emacs Lisp and C source code for `ding', `beep', SIGQUIT, and
"Quit" showed that such occurrences (and there are a _lot_ of them) are not
involved either.

In sum, it was not easy to find what was handling the `C-g' in this situation.
I finally tracked it down to a call to `sit-for' and thus ultimately to C
function `read_char'.

That call to `sit-for' was so ancillary to the general user interaction in the
minibuffer that I did not even think of it at first.  It was only after
searching unsuccessfully for what code might be intercepting the `C-g' and just
printing `Quit', and a fair amount of debugging (including via
`read-bell-function), that I eventually discovered the `sit-for' and its `C-g'
gotcha.

> Much more important, though, is 
> that while not in a command loop (e.g., during `sit-for'), 
> `quit-char' is turned directly into a `quit' signal (not 
> SIGQUIT; that's an unrelated Unix concept).  That signal 
> unwinds the call stack until it hits a recursive editing 
> level (which catches all exceptions) and prints "Quit".

Yes, that's what I was trying to say wrt the code in `read_char'.

(I think you meant `quit_char', not `quit-char'.  See also thread "`quit_char',
`set-quit-char', and `set-input-mode'", which suggests that maybe we should have
a Lisp-level equivalent of the C variable `quit_char'.)

(SIGQUIT might be unrelated to a `quit' signal, but it is present quite a bit in
the Emacs C code and even a bit in the Lisp code.)

> From a conceptual if not a C-implementation point of view, 
> then, `read-char' and so forth do not handle C-g in any 
> special way.  That is to say, it does what it always does, 
> and aborts the currently running Lisp code.

"Aborts the currently running Lisp code" does not, in this case, mean that it
returns to top level.  It seems to mean that it aborts `sit-for' (?).

> As it is global and standard, they do not document that behavior;
> see (elisp)Quitting.

Yes, I read that, of course (see bug #11458).  Including this part:

 "Typing `C-g' while the command loop is waiting for
  keyboard input does not cause a quit; it acts as an
  ordinary input character."

It could be argued that `sit-for' matches that description, at least partly, in
its use of `read-event'.  But it does not match the behavior described.

Or rather, `read-event' & compagnie, while reading keyboard input, do not seem
to just treat `C-g' as an ordinary input character, but rather they handle it
directly (in addition to returning it).  They seem to "cause a quit", AFAICT.

Or maybe I'm not paying close enough attention to "command loop" here, and
focusing on "while ... waiting for keyboard input".  IOW, maybe I'm trying to
read more (or less) into this passage than was meant.

> > My next question is whether `sit-for' itself should do the 
> > same thing: bind `inhibit-quit' to t.
> 
> Surely not.  Aborting a command like yours in a normal 
> minibuffer would then abort the whole minibuffer (because 
> you'd get C-g in `unread-command-events' AND the `quit' 
> signal).

Binding it would, and does, simply cause `C-g' in the minibuffer to do what
`C-g' in the minibuffer does in general and is meant to do there:
`abort-recursive-minibuffer'.  TRT?

Not binding it causes `C-g' to just beep and print `Quit', which is not really
what a user wants, IMO.  In that case, the `C-g' does not really quit anything,
AFAICT, except perhaps the `sit-for' itself.

What a user expects when s?he uses `C-g' in the minibuffer is
`abort-recursive-edit', IMO.  S?he does not know or care whether a `sit-for'
might be in progress.

But I won't insist that `sit-for' should simply pass the `C-g' on to the calling
context so that its current binding (e.g. `abort-recursive-edit' in the
minibuffer) can take effect.  I only posed the question, for consideration by
those of you who understand this stuff better than I.

> And while it's easy to add a let-binding to get the 
> behavior you want, you couldn't ever go back were it the default.

I have to agree with that.  So part of the question I posed is whether one would
ever want/need to go back.  Dunno.  I don't see any reason for that, offhand,
but I agree that such a change to `sit-for' would remove the option (from
`sit-for').  Maybe it's as simple as asking whether `C-g' during `sit-for'
should quit only the `sit-for' (?), i.e., whether that is ever useful.

----

More importantly, let me just say that it took me a few _hours_ to figure out
what was going on.

Had _any_ of the functions I came across in my quest documented that it handled
`C-g' directly as a special case (preventing it from being handled in the
caller, via its key binding, etc.), then I would have found the answer
(understood) immediately.  (By "special case" I mean that it is treated there
differently from other events/chars that are read.)

That includes not only the doc strings of Lisp functions (e.g. `sit-for',
`read-event'), but even the code comments for the C functions (e.g.
`read_filtered_event', `read_char') - nada about `C-g'.

It wasn't until I finally got to the `read_char' code that I saw anything that
indicated that `C-g' was being handled.  (And yes, `read_char' is something very
different from `read-char'.)

Looking at the code for `sit-for', unless you happen to know that `read-event'
handles `C-g' directly, you (I) can easily get the impression that the `C-g'
char gets pushed onto `unread-command-events'.  (And that's the behavior I would
in fact expect/prefer.)

So yes, I disagree that this should not be documented - and yes, at the
individual function level.  It certainly does not hurt, IMO, to let users of a
function know that a `C-g' char is handled specially there, even if this is, as
you seem to say, something that people should know generally from reading (elisp
`Quitting').

Anyway, I do appreciate your reply/explanation, Davis.

Re: question about `sit-for' and `C-g'

[Davis Herring]

[My point-by-point reply, proved quite repetitive, so here are some
general points for later reference:]

0. From the standpoint of a user or Lisp programmer, Emacs is at any
moment either running a command or waiting for one (a key sequence).
These two states nest via recursive editing levels (and use of the
minibuffer is one such); only the top-most level counts.

1. The normal behavior of C-g, while a command is executing, is to
destroy that command and return to the wait that preceded it (printing
"Quit" as feedback).  (Internally, this is because any command loop
catches all signals, including the quit that destroys the command.)

2. You are expected to know #1 (and thus #0 to understand it), and as a
Lisp programmer to know that it applies to your programs in the absence
of special requests (`with-local-quit', for instance).

3. If you don't know #1, feel free to call that a documentation bug.
"Patches welcome."

4. The behavior you observed was this normal behavior; your command
(that ran `sit-for') was destroyed, and Emacs resumed waiting (in the
minibuffer) for further input.  `sit-for' was entirely irrelevant -- you
would have seen the same, normal behavior had your code been in a long
computation loop at the time.  `sit-for' does not have "special
behavior" with regards to C-g.

5. From #4, if `sit-for' is insufficiently documented, so are `let',
`while', and `funcall' (which are the common places a quit is checked).
 `sit-for' deals with input and they do not, but they treat C-g
identically (that is, not as input).

6. #1 is not special; there are other general concepts that are not
mentioned everywhere they have effect.  Keyboard macros can provide
input anywhere (but `read-event' doesn't mention them), advice can
change the meaning of any function (but `funcall' doesn't mention it),
etc.  Documenting every global feature everywhere is counterproductively
noisy.

> And I do want `C-g' to be handled by its current keybinding for each call to
> `sit-for' in my code.  For both of these reasons it makes sense to bind
> `inhibit-quit' in `icicle-sit-for'.]

Sure -- my point was that you need not duplicate the implementation of
`sit-for' merely to bind `inhibit-quit'.

> And searching Emacs Lisp and C source code for `ding', `beep', SIGQUIT, and
> "Quit" showed that such occurrences (and there are a _lot_ of them) are not
> involved either.
> 
> In sum, it was not easy to find what was handling the `C-g' in this situation.
> I finally tracked it down to a call to `sit-for' and thus ultimately to C
> function `read_char'.
> 
> That call to `sit-for' was so ancillary to the general user interaction in the
> minibuffer that I did not even think of it at first.  It was only after
> searching unsuccessfully for what code might be intercepting the `C-g' and just
> printing `Quit', and a fair amount of debugging (including via
> `read-bell-function), that I eventually discovered the `sit-for' and its `C-g'
> gotcha.

#2, #4

> "Aborts the currently running Lisp code" does not, in this case, mean that it
> returns to top level.  It seems to mean that it aborts `sit-for' (?).

#1

> Or rather, `read-event' & compagnie, while reading keyboard input, do not seem
> to just treat `C-g' as an ordinary input character, but rather they handle it
> directly (in addition to returning it).  They seem to "cause a quit", AFAICT.

#4

There actually is special (relative to the rest of Emacs) behavior here:
if `quit-flag' is non-nil during `read-char', it returns `quit_char'.
If `inhibit-quit' is also non-nil, `quit-flag' is cleared (since the
quit has been "consumed" as input); otherwise the quit remains
outstanding and the signal will be raised soon thereafter.  (This is
arguably a bug: (setq n (read-event)) actually sets n to 7 on C-g
because the `setq' happens before the quit is signaled.)

However, leaving aside the delayed quit, this is invisible to the Elisp
programmer except that "when `inhibit-quit' is set, `read-event' can
read C-g", which is hardly counterintuitive.

> Or maybe I'm not paying close enough attention to "command loop" here, and
> focusing on "while ... waiting for keyboard input".  IOW, maybe I'm trying to
> read more (or less) into this passage than was meant.

#1

> Binding it would, and does, simply cause `C-g' in the minibuffer to do what
> `C-g' in the minibuffer does in general and is meant to do there:
> `abort-recursive-minibuffer'.  TRT?
> 
> Not binding it causes `C-g' to just beep and print `Quit', which is not really
> what a user wants, IMO.  In that case, the `C-g' does not really quit anything,
> AFAICT, except perhaps the `sit-for' itself.
> 
> What a user expects when s?he uses `C-g' in the minibuffer is
> `abort-recursive-edit', IMO.  S?he does not know or care whether a `sit-for'
> might be in progress.

#0  (The user must care because they must know whether a command is
running.  If they want to kill the minibuffer, they know that's two
levels and so two `C-g's.)

If you're writing a command that pretends to not exist so that keys that
arrive during its execution are treated as they would be were it not
executing, yes you will have to do strange things like bind
`inhibit-quit', set `unread-command-events', etc.  This should not be
surprising, as you are writing a command that needs to operate outside
the standard rules.

> Maybe it's as simple as asking whether `C-g' during `sit-for'
> should quit only the `sit-for' (?), i.e., whether that is ever useful.

Then a loop
  (while ... (do-something-inexpensive) (sit-for 1))
would be difficult to interrupt because nearly every C-g would hit a
`sit-for'.

> More importantly, let me just say that it took me a few _hours_ to figure out
> what was going on.

Unfortunate that it was so painful: #3.

> Had _any_ of the functions I came across in my quest documented that it handled
> `C-g' directly as a special case (preventing it from being handled in the
> caller, via its key binding, etc.), then I would have found the answer
> (understood) immediately.

#5, and #6.

> (By "special case" I mean that it is treated there differently from other
> events/chars that are read.)

#1: this is not a special case, any more than ^C is a special case when
a program is reading from the terminal.  It kills the process whether or
not it's reading at the time.

> Looking at the code for `sit-for', unless you happen to know that `read-event'
> handles `C-g' directly, you (I) can easily get the impression that the `C-g'
> char gets pushed onto `unread-command-events'.  (And that's the behavior I would
> in fact expect/prefer.)

#2

> So yes, I disagree that this should not be documented - and yes, at the
> individual function level.  It certainly does not hurt, IMO, to let users of a
> function know that a `C-g' char is handled specially there, even if this is, as
> you seem to say, something that people should know generally from reading (elisp
> `Quitting').

#5, #6

> Anyway, I do appreciate your reply/explanation, Davis.

Glad to be of assistance!

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

RE: question about `sit-for' and `C-g'

[Drew Adams]

Thanks for a carefully prepared reply, with useful info.

Just a couple of remarks, which you can think of as questions if you like.

> 4. The behavior you observed was this normal behavior; your command
> (that ran `sit-for') was destroyed, and Emacs resumed waiting (in the
> minibuffer) for further input.  `sit-for' was entirely 
> irrelevant -- you would have seen the same, normal behavior had
> your code been in a long computation loop at the time.  `sit-for'
> does not have "special behavior" with regards to C-g.

Yes, well put.  But it was not obvious to me, as I said, since I had nearly
forgotten that the command in question (which cycles to the next completion
candidate) called `sit-for'.

And the "destroying" of that command was not at all obvious, since it had
already done its real job of cycling to the next candidate and was just
temporarily displaying help about it in the mode line, with a `sit-for' wait.

So in terms of the most-observable behavior, no command appeared to be
aborted/quit.  The `C-g' seemed to quit only the `sit-for' because that was the
last thing that the command did.

I'm not at all disagreeing with you here - just pointing out my observations
while I was trying to figure things out.  Though I knew the points you make, it
was not clear to me what was happening, and rather than start from such an
understanding I tried to narrow down who was handling that particular `C-g'
event.

> There actually is special (relative to the rest of Emacs) 
> behavior here: if `quit-flag' is non-nil during `read-char', it
> returns `quit_char'.

Yes, that was a point that I made.  (But I think you mean `read_char', not
`read-char'.)

> If `inhibit-quit' is also non-nil, `quit-flag' is cleared (since the
> quit has been "consumed" as input); otherwise the quit remains
> outstanding and the signal will be raised soon thereafter.  (This is
> arguably a bug: (setq n (read-event)) actually sets n to 7 on C-g
> because the `setq' happens before the quit is signaled.)
>
> However, leaving aside the delayed quit, this is invisible to 
> the Elisp programmer except that "when `inhibit-quit' is set,
> `read-event' can read C-g", which is hardly counterintuitive.
>
> > What a user expects when s?he uses `C-g' in the minibuffer is
> > `abort-recursive-edit', IMO.  S?he does not know or care 
> > whether a `sit-for' might be in progress.
> 
> #0  (The user must care because they must know whether a command is
> running.  If they want to kill the minibuffer, they know that's two
> levels and so two `C-g's.)

See above.  No, when this particular `sit-for' is invoked it is not at all
obvious (to a user, and even to me when I was trying to debug what was
happening) that some command is still executing.  From all appearances, the last
command (to cycle to the next candidate) has finished, including its display of
help info in the mode line.  The last thing it does is call `sit-for', and that
`sit-for' wait is pretty invisible to a user.

> If you're writing a command that pretends to not exist so that keys that
> arrive during its execution are treated as they would be were it not
> executing,

See above.  That is not really the case here.  The cycle-to-next command just
makes the next candidate current, then displays some text about it in the mode
line, and then calls `sit-for' before restoring the mode line.

Keys arriving during a `sit-for' generally cancel the `sit-for' wait.  They are
typically processed normally.  That's all.  That's also the user expectation for
the `C-g' here (even if s?he  knew that it happened during a `sit-for'): just
apply the keybinding for `C-g'.

And that's the behavior obtained by binding `inhibit-quit' to t, because
`read-event' returns the `C-g' character in any case ("because the `setq'
happens before the quit is signaled").

> yes you will have to do strange things like bind
> `inhibit-quit', set `unread-command-events', etc.  This should not be
> surprising, as you are writing a command that needs to operate outside
> the standard rules.

Bof.  (But I know what you mean, and it's not incorrect.)

> > Maybe it's as simple as asking whether `C-g' during `sit-for'
> > should quit only the `sit-for' (?), i.e., whether that is 
> ever useful.
> 
> Then a loop (while ... (do-something-inexpensive) (sit-for 1))
> would be difficult to interrupt because nearly every C-g would hit a
> `sit-for'.

I don't think so.  If `sit-for' binds `inhibit-quit' (as in my case), what
happens is that a `C-g' char is returned and then handled normally, e.g., by its
keybinding.

That's exactly what happens in my (corrected) code, except that it is `when'
rather than `while', and the `sit-for' period is (by default) longer.  Because
it is longer, the same thing is true in the end: a `C-g' typically falls within
`sit-for'.

The binding of `inhibit-quit' to non-nil inside (my version of) `sit-for' just
makes the `C-g' char pass through (so that it is handled by its keybinding, in
this case).

However, your point is valid if the code does something after the `sit-for'.  In
that case, without binding `inhibit-quit' that post-sit-for code would be
skipped, whereas with its binding it would be run.

In my case and in your example, there is nothing after the `sit-for', so there
is no difference except the handling of `C-g'.  (Well, you could argue that
`do-something-inexpensive' occurs also after the `sit-for'...)

Anyway yes, with such a modification to your example it provides a good reason
why `sit-for' should not, itself, bind `inhibit-quit'.

> Glad to be of assistance!

Thanks again.