Need a reasonable way to either cancel `ReadConsole` or poll for text input

[alexrp]

In my library I expose a terminal input API that looks like this:

public static class Terminal
{
    public static ValueTask<string?> ReadLineAsync(CancellationToken cancellationToken = default)
    {
        // ..
    }
}

On Unix, implementing cancellation support was quite easy:

• Create an anonymous pipe at startup.
• When the CancellationToken is triggered, write a dummy value to the write end of the pipe.
• In ReadLineAsync, poll for input on the read end of the pipe and stdin.
• If the poll returns indicating input on the pipe, drain the pipe and throw OperationCanceledException.
• If the poll returns indicating input on stdin, actually read the data and return it.

(For reference, the implementation of the above can be found here and here.)

I would now like to implement something similar for Windows. Unfortunately, as far as I can tell, this is bordering on impossible at the moment.

I naïvely tried to replicate the approach above on Windows, only to discover that WaitForMultipleObjects does not support polling on pipes. I replaced the pipe with an event since WaitForMultipleObjects supports those. I then ran into another problem: Polling on a console input handle will return when any INPUT_RECORD arrives, not just KEY_EVENT_RECORDs. I decided to try CancelIo and CancelSynchronousIo on the off chance that they'd work instead of polling, but they just don't work on console input, apparently. At that point, things got hairy; I went back to the polling approach and tried to inspect the input buffer looking for KEY_EVENT_RECORDs specifically, discarding other event records, and then resuming the wait if there are no KEY_EVENT_RECORDs. Besides being very gross and hacky, this fell apart quickly as it turns out there's no clean way to figure out if a given KEY_EVENT_RECORD (or a series of them) will actually result in text input being available on the next ReadConsole call. Worse yet, even when I did hack together some heuristics, the behavior turned out to be different between CMD and Windows Terminal. At that point, I gave up and ripped out Windows cancellation support.

So I suppose this issue boils down to me asking: Is there a way to achieve what I'm trying to do that I just haven't realized yet? If not, could one be implemented?

[eryksun]

try CancelIo and CancelSynchronousIo on the off chance that they'd work instead of polling,
but they just don't work on console input

In Windows 8+, CancelSynchronousIo() works for a console ReadFile() or ReadConsoleW(), but only in a half-baked way. It respectively cancels the NtReadFile() or NtDeviceIoControlFile() request on the client side. However, the console host doesn't cancel its operation. It continues a cooked read, and the contents of the read are discarded after the user enters a line.

It would be a good thing to properly support cancelling I/O requests in the console host, if the design permits it. This may require changes to the console device driver, condrv.sys, if it's currently not canceling the associated IOCTL request in the console. I haven't checked that.

Note that ReadConsoleW() succeeds with the last error set to ERROR_OPERATION_ABORTED when the underlying NtDeviceIoControlFile() call returns either STATUS_ALERTED (due to Ctrl+C or Ctrl+Break) or STATUS_CANCELLED (due to a cancel). The latter can be distinguished by initially setting lpNumberOfCharsRead = (DWORD)-1. It will be set to 0 if the read is interrupted by Ctrl+C or Ctrl+Break.

Since Windows 8, ReadFile() for a console file is no longer special cased. It uses a normal NtReadFile() system call. ReadFile() generically handles the console's STATUS_ALERTED result for Ctrl+C or Ctrl+Break as a success code, without setting the last error. Thus with ReadFile(), a console read that's canceled by Ctrl+C or Ctrl+Break is indistinguishable from an empty read (i.e. a line that starts with Ctrl+Z). OTOH, ReadFile() generically handles STATUS_CANCELLED as a failure code, which sets the last error to ERROR_OPERATION_ABORTED.

WaitForMultipleObjects does not support polling on pipes.

The system wait routines support waiting on file objects. It's generally only meaningful in user mode when waiting for I/O completion with an asynchronous-mode file. If I/O requests never overlap, it's safe to wait for I/O completion by waiting on the file object itself. (It's recommended to use events, APCs, or a completion port instead of waiting on the file object, since generally there will be multiple pending I/O requests.) Either end of a named pipe can be opened in asynchronous mode by passing the flag FILE_FLAG_OVERLAPPED to the CreateNamedPipeW() or CreateFileW() call.

Console input files are an exception to this rule. As background, note that the File type can reuse the FsContext2 field of a file object to store the address of a custom event to wait on if a file object needs non-standard wait semantics. This is how waiting on a console input file implements the POSIX pattern of waiting for a synchronous file to be ready for I/O. Otherwise, the address of the default event to use when waiting on a file object is stored in its Event field, which gets signaled for I/O completion.

Polling on a console input handle will return when any INPUT_RECORD arrives

The most noise is from mouse events, which can be disabled. But you'll still have menu, focus, and window size events in the input buffer that have to be ignored.

A high-level PeekConsoleW() function that's non-blocking might make this simpler:

BOOL PeekConsoleW(
  [in]            HANDLE  hConsoleInput,
  [out, optional] LPVOID  lpBuffer,
  [in]            DWORD   nNumberOfCharsToRead,
  [out, optional] LPDWORD lpNumberOfCharsRead,
  [out, optional] LPDWORD lpNumberOfCharsAvail,
  [out, optional] LPDWORD lpNumberOfCharsLeftThisLine
);

This mirrors PeekNamedPipe(), but based on characters and lines instead of bytes and messages. For example, PeekConsoleW(h, NULL, 0, NULL, &m, &n) would set m to the total number of characters in the input buffer and n to the number of characters up to and including a "\r" or "\r\n" line ending, if any. The value of n would be zero if the input buffer doesn't contain a line ending.

[eryksun]

Off-topic comment:

The library's SendSignal() method is flawed. GenerateConsoleCtrlEvent() takes a process group ID, or group 0 for all processes in the console session (including the calling process). The only documented way to know the group ID of a process is to spawn it with the process creation flag CREATE_NEW_PROCESS_GROUP. GenerateConsoleCtrlEvent() supports CTRL_C_EVENT (cancel) and CTRL_BREAK_EVENT. It does not support CTRL_CLOSE_EVENT or CTRL_SHUTDOWN_EVENT.

The cancel event is initially ignored by the root process of a new group. This state gets inherited by child processes. The cancel event can be enabled manually via SetConsoleCtrlHandler(NULL, FALSE). The break event, on the other hand, is never ignored.

For console apps, the nearest equivalent to a POSIX process group is to spawn the root process of a new group with CREATE_NEW_PROCESS_GROUP, and add the process to a job object. When it's time to terminate the group, akin to killpg(pgrp, SIGTERM) in POSIX, call GenerateConsoleCtrlEvent(CTRL_BREAK_EVENT, rootProcessId). The default handler calls ExitProcess(), so at least loaded DLLs will be notified to shut down gracefully. Any processes that remain after waiting can be terminated forcefully via TerminateJobObject(), which is equivalent to following up with killpg(pgrp, SIGKILL) in POSIX.

[alexrp]

The most noise is from mouse events, which can be disabled. But you'll still have menu, focus, and window size events in the input buffer that have to be ignored.

Even if entirely discarding these, the primary challenge seemed to be interpreting KEY_EVENT_RECORDs correctly. I never managed to figure out a reliable way to know whether a given KEY_EVENT_RECORD would mean that text is available to be read.

See vezel-dev/cathode#61 for some background.

---

The library's SendSignal() method is flawed.

Originally, it was just used to synthesize signals for the current process. That should be roughly equivalent on Windows and Unix.

I later used it for sending signals to child processes which is indeed where it becomes problematic. I've been meaning to remove that method for this exact reason.

It does not support CTRL_CLOSE_EVENT or CTRL_SHUTDOWN_EVENT.

This particular issue was addressed in vezel-dev/cathode@db81ecf.

[eryksun]

the primary challenge seemed to be interpreting KEY_EVENT_RECORDs correctly.

That's why I suggested the addition of PeekConsoleW(), so applications wouldn't have to guess at what ReadConsoleW() would return, or accommodate different behavior in the console host across various versions and operating modes (i.e. classic vs pseudoconsole).

Note that if line-input mode is enabled and there's no line ending in the input buffer, ReadConsoleW() has to be called to let the user user type text into the console's line editor. This is a blocking call, and currently there's no proper support to cancel it, as I discussed in regard to CancelSynchronousIo().

Note that the classic console is not "CMD". That's a CLI shell that uses standard I/O. Windows Terminal ships with a more up to date version of the console host named "openconsole", in place of the system "conhost". So sometimes behavior differs due to the version, but it's mostly down to classic vs pseudoconsole mode, and whether virtual-terminal mode is enabled.

Originally, it was just used to synthesize signals for the current process. That should be roughly equivalent on Windows and Unix.

In POSIX, pid 0 includes all processes in the caller's process group. In Windows, group 0 includes all processes in the console session. Sending a signal to just the current process is possible in POSIX, but nothing like that is possible for Ctrl+C or Ctrl+Break in Windows.

Calling GenerateConsoleCtrlEvent() is fine for a child process as long as it's created with CREATE_NEW_PROCESS_GROUP, and as long as it's okay that the event is sent to its descendants in the console session that are in the group. Unfortunately, passing this flag requires calling CreateProcessW() directly. It's not supported by .NET.

This particular issue was addressed in vezel-dev/cathode@db81ecf.

That update mistakenly removed CTRL_BREAK_EVENT and kept CTRL_CLOSE_EVENT. I'd map CTRL_BREAK_EVENT to TerminalSignal.Terminate. It's never ignored and the closest to SIGTERM. The equivalent of SIGKILL is TerminateJobObject() or TerminateProcess().

[malxau]

As far as PeekConsoleW, note we have PeekConsoleInputW, but I think the problem Alex is pointing out is there's no way to peek (nonblocking), process events, then consume the events that are processed from the queue. The only way is to call ReadConsoleInput and hope that nothing else has removed those events in the meantime, because if they did, the read will block. The events need to be consumed somehow otherwise the handle remains signalled so there's no way to wait for more.

I think any PeekConsoleW equivalent to ReadConsoleW has the same issue: it would need to specify a timestamp/identifier that can later be used to say "please consume these specific things/please consume up to this point in time."

[alexrp]

@malxau

Well, to be clear, ideally I don't even want to have to deal with INPUT_RECORDs. That was just one avenue I explored in my quest to achieve either (text) polling or cancellation.

Note that when I say "polling" here, I mean poll(2), which blocks until input is available. What I do on Unix is poll on stdin and the read end of a pipe. When I want to cancel, I write something to the write end of the pipe. When poll returns, I can then tell whether it's because the user typed something (stdin) or because cancellation was requested (pipe). This isn't 'true' cancellation but it's close enough.

The problem with this approach is that, on Windows, WaitForMultipleObjects (the poll(2) sort-of-equivalent) on a console input handle does not poll for text, but rather for input records (of any kind - mouse, focus, etc included). Even if there was a way for me to process those 'atomically', it would be very difficult for me to match the behavior of the console host in regards to how INPUT_RECORDs are translated to text for ReadConsole purposes. It also seems like a total breakdown in the console abstraction on at least two levels.

It's probably not acceptable to change WaitForMultipleObjects on a console input handle to poll for text only, due to compatibility concerns. Given @eryksun's comments, I would imagine the only sane way forward would be to support CancelSynchronousIo on console input handles. (IIRC, last time I tested, I got ERROR_NO_MATCH when calling CancelSynchronousIo on a thread blocked in ReadConsole, but I would need to double-check to be sure.)

---

@eryksun

In POSIX, pid 0 includes all processes in the caller's process group. In Windows, group 0 includes all processes in the console session. Sending a signal to just the current process is possible in POSIX, but nothing like that is possible for Ctrl+C or Ctrl+Break in Windows.

Right, that's why GenerateSignal is implemented as kill(0, sig) rather than kill(getpid(), sig). It seemed the only way to get reasonably consistent behavior between Windows and Unix.

Unfortunately, passing this flag requires calling CreateProcessW() directly. It's not supported by .NET.

This is why I'll likely end up removing that ChildProcess.SendSignal method. At least for as long as ChildProcess is implemented in terms of System.Diagnostics.Process (as opposed to calling Win32 APIs directly) there isn't a way for me to set CREATE_NEW_PROCESS_GROUP. ☹️ I might remedy that one day once I've moved terminal platform code to a native library...

That update mistakenly removed CTRL_BREAK_EVENT and kept CTRL_CLOSE_EVENT.

Good catch! Will fix that.

I'd map CTRL_BREAK_EVENT to TerminalSignal.Terminate. It's never ignored and the closest to SIGTERM. The equivalent of SIGKILL is TerminateJobObject() or TerminateProcess().

In principle I agree completely and this is what I wanted to do originally.

Unfortunately, an (IMO) poor decision was made during the design of the .NET 6 System.Runtime.InteropServices.PosixSignalRegistration API to map SIGTERM to CTRL_SHUTDOWN_EVENT, so I decided to be consistent with that to avoid confusion.

[eryksun]

API to map SIGTERM to CTRL_SHUTDOWN_EVENT, so I decided to be consistent with that to avoid confusion.

Their choices aren't bad. Mapping CTRL_BREAK_EVENT to SIGQUIT isn't without merit, since it's associated with Ctrl+\ in the terminal, a common way to immediately kill a process and return to the shell. Though in Linux it defaults to an abnormal termination that dumps a core file, which is more extreme than Ctrl+Break. I think mapping it to SIGTERM is more useful considering the break event is the only one that we can rely on to always work more or less like sending SIGTERM to a process group. AFAIK, it's not normal to send SIGQUIT to a child process or group via kill() or killpg().

Mapping CTRL_CLOSE_EVENT to SIGHUP makes sense, except CTRL_CLOSE_EVENT can't be ignored or handled in a way that lets the current process continue. By default a process has 5 seconds (HungAppTimeout) to exit on its own before the system terminates it.

CTRL_SHUTDOWN_EVENT is mapped to SIGTERM probably because most POSIX systems shut down by first sending SIGTERM to running processes, followed by SIGKILL after a timeout. For some reason they're not also handling CTRL_LOGOFF_EVENT. The shutdown and logoff 'console' events are sent directly by the system (not by the console host) to any process that isn't connected to a window station and desktop -- i.e. a process that doesn't load user32.dll, which can be hard to prevent since many DLLs depend on it.

[alexrp]

Ping - any chance this can get triaged? It is still a major roadblock in supporting sane input cancellation on Windows.

[DHowett]

I know that this is a long shot, but I was just reading the initial request (sorry we've left this one quiet for so long) and something caught my eye:

I then ran into another problem: Polling on a console input handle will return when any INPUT_RECORD arrives, not just KEY_EVENT_RECORDs.

We recently documented an API that should have been public from the get-go, ReadConsoleInputEx. Unlike Read/Peek, it allows you to specify a set of read flags that effectively break out the individual behaviors of those two functions[1].

I think you might be able to get what you're looking for by using CONSOLE_READ_NOREMOVE. You can wait for input to arrive (don't submit NOWAIT), but you can leave the events in the queue if they're not what you're looking for. It's effectively Peek, but it'll wait for input.

It is supported all the way down to Windows 7.

[1] In fact, Read and Peek just call ReadEx internally; Read passes no flags, and Peek passes NOREMOVE|NOWAIT

[alexrp]

@DHowett Hmm, at first glance, I don't think this will solve the problem. It seems to me that this isn't meaningfully any different from using WaitForMultipleObjectsEx on a console input handle and a cancellation event handle. If anything, achieving cancelability with ReadConsoleInputEx seems like it would be more trouble than that approach.

It would also still require me to interpret the key events returned and pray that I can figure out how to determine if the key events in the buffer correspond to what ReadConsole considers to be valid text input - which is untenable.

[alexrp]

Just checking in here again. Is there any hope of making progress in this area? This issue (AFAIK) remains a hard blocker for reasonable input cancellation support in Windows terminal apps.