Struct EventSource 

pub struct EventSource<I>
where
    I: Input,
{ /* private fields */ }

Wakeable event source backed by a platform readiness primitive.

EventSource is the synchronous owner of terminal input. It stores pending bytes, a Decoder, an event queue, deadline state for ambiguous ESC prefixes and open bracketed pastes, and the platform handles needed for wakeups and resize notifications.

Construct it with EventSource::new. Use EventSource::poll to perform I/O and wait for queued events, EventSource::try_read to pop an already queued event, or EventSource::read to block until one event is available. The type is generic over the platform Input handle.

Implementations

impl<I> EventSource<I>

where I: Input,

pub fn esc_timeout(&self) -> Duration

Return the configured escape-sequence timeout.

This is the duration used to disambiguate a physical Escape key from an Alt-prefixed key or a partial control sequence. Reading it has no side effects and never performs I/O.

pub fn with_esc_timeout(self, timeout: Duration) -> Self

Set the escape-sequence timeout.

timeout is how long the source waits for a continuation byte before a buffered partial escape sequence is force-resolved. The default is DEFAULT_ESC_TIMEOUT. A zero duration makes ambiguous prefixes expire on the next poll cycle.

This is a consuming builder intended to be chained after EventSource::new. It does not inspect or clear any already-buffered input and never panics.

pub fn with_paste_idle_timeout(self, timeout: Option<Duration>) -> Self

Set the idle timeout for an open bracketed paste.

If no further input arrives before timeout, the source flushes any held bytes as a final Event::PasteChunk, synthesizes Event::PasteEnd, and leaves paste mode. Passing None disables this safety net and waits indefinitely for a real terminator. The default is Some(DEFAULT_PASTE_IDLE_TIMEOUT).

This is a consuming builder intended to be chained after EventSource::new. It never panics.

pub fn waker(&self) -> Waker

Return a cloneable Waker bound to this source.

Use the returned handle from another thread to interrupt a blocking EventSource::poll or EventSource::read. Cloning the waker does not clone the source or its input handle.

pub fn handle_resize(&self) -> bool

Return whether out-of-band resize handling is enabled.

On Unix, true means a readable SIGWINCH pipe can produce Event::Resize. On Windows, resize records are delivered in-band and this flag has no practical effect.

pub fn set_handle_resize(&mut self, enable: bool)

Control whether the source delivers Event::Resize from the kernel’s out-of-band window-resize notification (SIGWINCH on Unix). Defaults to true.

Set this to false after enabling in-band resize reports (DEC mode 2048): the terminal then reports size changes in-band as CSI 48 t, which the decoder surfaces as Event::Resize, so leaving the SIGWINCH path on would deliver each resize twice. Restore it to true when in-band reporting is disabled again.

No effect on Windows, where resize is always delivered in-band through the decoder.

pub fn poll(&mut self, timeout: Option<Duration>) -> Result<bool>

Wait up to timeout for at least one event to become available.

This method performs I/O, drains decoder output into the internal queue, handles resize notifications, and resolves any expired ESC or paste deadlines. None means block until an event or wake; Some(Duration::ZERO) means perform a non-blocking readiness pass.

Returns:

• Ok(true) when the queue has at least one event;
• Ok(false) when the timeout elapsed or a paired Waker interrupted the wait without producing an event;
• Err(_) for fatal input or platform readiness errors.

pub fn try_read(&mut self) -> Option<Event>

Return the next queued event without performing I/O.

This only pops the internal queue. Call EventSource::poll first when the queue may be empty but input could be ready. Returns None when no event is currently queued.

pub fn read(&mut self) -> Result<Event>

Block until the next event is available, then return it.

This repeatedly checks the queue and calls EventSource::poll with no caller timeout. It returns the next Event on success.

Returns io::ErrorKind::Interrupted if a paired Waker fired while waiting, and propagates fatal input/readiness errors.

pub fn unread(&mut self, event: Event)

Return an event to the front of the queue, so the next read / try_read yields it before anything already queued. Use to put back an event read while waiting for a specific reply (e.g. a cursor-position report), preserving it for normal delivery. Restore a batch in original order by unreading in reverse.

pub fn end_paste(&mut self)

Force-exit bracketed paste mode.

If the decoder is currently inside a paste, this flushes any pending bytes as a Event::PasteChunk, queues Event::PasteEnd, and clears paste state so subsequent bytes parse as ordinary input. Use it when an embedding application enforces a paste size cap, user cancellation, or a custom watchdog. It has no effect outside paste mode and never panics.

impl<I> EventSource<I>

where I: Input,

pub fn new(input: I) -> Result<Self>

Build a new Unix event source for input.

The handle is used both for byte reads and as the TIOCGWINSZ target when SIGWINCH fires, so it should refer to the terminal whose size the caller cares about. Construction creates two non-blocking self-pipes, subscribes to the shared SIGWINCH fan-out, and registers the input, wake, and resize fds with the selected poll backend.

Timeouts start at DEFAULT_ESC_TIMEOUT and DEFAULT_PASTE_IDLE_TIMEOUT; override them with EventSource::with_esc_timeout and EventSource::with_paste_idle_timeout.

Returns any OS error from pipe creation, fd configuration, SIGWINCH subscription, or poller construction. It does not read from input.

impl<I> EventSource<I>

where I: Input + 'static,

pub fn into_stream(self) -> EventStream<I>

Convert this source into a thread-backed EventStream.

The source is wrapped in Arc<Mutex<_>> owned solely by the stream. To keep reading the source synchronously alongside the stream, build the Arc<Mutex<_>> yourself and use EventStream::from_shared.