cancelreader

The selectCancelReader implementation uses the POSIX select syscall to allow a blocking Read call to be interrupted by a cancellation signal.

It works by creating an internal os.Pipe. When Cancel() is called, a byte is written to the pipe's writer. The Read method uses unix.Select to monitor both the target file descriptor and the pipe's reader descriptor. If the pipe's descriptor becomes ready, the Read method recognizes this as a cancellation signal and returns ErrCanceled.

Limitations:

• This implementation is only available on solaris, darwin, freebsd, netbsd, openbsd, or dragonfly.
• It only works if the input reader implements the File interface and its file descriptor is less than unix.FD_SETSIZE (typically 1024). If these conditions are not met, it falls back to a different implementation.

To interrupt a blocking read operation, use a CancelReader. When Cancel() is invoked, the subsequent or currently blocking Read call will return 0, ErrCanceled.

Note: The underlying reader must satisfy the File interface (providing an Fd() method) for the cancellation to successfully interrupt the syscall via select.

// Assuming 'r' is a CancelReader and 'file' is an io.Reader that implements File
// err := r.Read(data)
// if errors.Is(err, cancelreader.ErrCanceled) {
//     // Handle cancellation
// }
// 
// r.Cancel()

Use NewReader to wrap an existing reader and obtain a version that supports cancellation.

Signature: NewReader(r io.Reader) (Reader, error)

Returns:

• A Reader which implements io.Reader and provides a Cancel() method.
• An error if the reader cannot be wrapped.

r, err := cancelreader.NewReader(file)

When a Read call is successfully interrupted by Cancel(), it returns an error. Use errors.Is with cancelreader.ErrCanceled to detect this specific state.

if errors.Is(err, cancelreader.ErrCanceled) {
    // The read was successfully interrupted
}

The CancelReader (implemented by selectCancelReader) provides the following methods to manage lifecycle and cancellation:

• Read(data []byte) (int, error): Reads data from the underlying reader. If the reader is canceled via Cancel(), this returns 0, ErrCanceled.
• Cancel() bool: Sends a signal to interrupt the current Read operation. Returns true if the signal was sent successfully.
• Close() error: Closes the internal pipes used for signaling. Should be called to clean up resources.

The Read(data []byte) method reads data into the provided slice.

If the reader has been canceled (either before the call or during the wait), it returns 0 and ErrCanceled. Otherwise, it returns the number of bytes read and any error encountered.

// data is the buffer to fill
n, err := reader.Read(data)
if err == cancelreader.ErrCanceled {
	// Handle cancellation
}

Use NewReader(reader io.Reader) to create a reader that supports cancellation.

On Windows, if the provided reader is a File with the same file descriptor as os.Stdin, the returned CancelReader can interrupt blocking read calls. In this specific case, the Cancel() method returns true if the cancellation was successful.

If the input reader is not os.Stdin, the implementation falls back to a standard reader where Cancel() does nothing and always returns false.

// Example usage for interrupting os.Stdin
reader, err := cancelreader.NewReader(os.Stdin)
if err != nil {
	log.Fatal(err)
}
defer reader.Close()

// In another goroutine or via signal handler:
// reader.Cancel() will interrupt the blocking Read call below

buf := make([]byte, 1024)
n, err := reader.Read(buf)

The Cancel() method marks the reader as canceled and attempts to interrupt any ongoing Read() calls.

Windows Specific Behavior: On Windows Terminal, WaitForMultipleObjects may sometimes return immediately without input being available. If this occurs, a graceful cancellation of an ongoing read is not possible, and Cancel() will return false.

Return Value:

• true: The cancellation of the ongoing Read() was successful.
• false: The cancellation failed (e.g., due to the Windows Terminal behavior mentioned above).

success := reader.Cancel()
if !success {
	// Handle case where cancellation didn't interrupt the current Read
}

The File interface extends io.ReadWriteCloser and provides access to low-level file information, specifically the file descriptor and the file name.

type File interface {
	io.ReadWriteCloser
	Fd() uintptr
	Name() string
}

Use NewReader to wrap an io.Reader with a CancelReader. This allows you to interrupt blocking read operations.

Behavioral Constraints:

• If the input reader is a *os.File, the returned cancel function can interrupt a blocking read call. The cancel function returns true if the cancellation was successful.
• If the input reader is not a *os.File, or if the file descriptor is 1024 or larger, the cancel function will do nothing and always return false.
• On Unix-like systems (specifically Solaris in this implementation), the mechanism is based on the posix select syscall.

reader, err := cancelreader.NewReader(myFile)
if err != nil {
    // handle error
}

// To cancel a blocking read:
success := reader.Cancel()

When running on platforms that do not support native cancellation (such as certain non-standard operating systems), NewReader provides a fallback implementation. It returns a CancelReader that wraps an io.Reader but does not actually support the cancellation functionality. This ensures that code expecting a CancelReader interface can still run, even if it cannot be interrupted.

import "github.com/muesli/cancelreader"

// reader is your standard io.Reader
// cancelReader will satisfy the CancelReader interface but won't support cancellation
cancelReader, err := cancelreader.NewReader(reader)