module RatatuiRuby::SyntheticEvents

Ruby-only event queue for synthetic events.

Native events flow through the Rust backend. Synthetic events bypass it. Runtimes (Tea, Kit) check this queue and handle events like Event::Sync specially.

*For runtime authors:* Check pending? each loop iteration after polling native events. When true, pop the event and handle it. For Event::Sync, wait for pending threads and process background results before continuing.

*For app developers:* Push Event::Sync when you need async results before continuing. The runtime will block until all pending work completes. Use this for “ensure saves complete before quit.”

*For test authors:* Use inject_sync between events to create synchronization points. This enables deterministic testing of async behavior.

Example

# Production: ensure async saves finish before exiting
RatatuiRuby::SyntheticEvents.push(RatatuiRuby::Event::Sync.new)

# Runtime authors: check in your event loop
if RatatuiRuby::SyntheticEvents.pending?
  event = RatatuiRuby::SyntheticEvents.pop
  handle_sync if event.sync?
end

Public Class Methods

clear ()

Source

# File lib/ratatui_ruby/synthetic_events.rb, line 93
def clear
  @mutex.synchronize { @queue.clear }
end

Clears all pending synthetic events.

Test helpers call this during teardown to reset state between tests.

inline_sync! ()

Source

# File lib/ratatui_ruby/synthetic_events.rb, line 65
def inline_sync!
  @inline_sync = true
end

Enables inline sync mode for deterministic event ordering.

Call once at startup. Cannot be disabled.

When enabled, inject_sync routes through the native event queue and poll_event returns Event::Sync like any other event. This ensures sync events are processed in sequence with key events.

Runtimes that need ordering guarantees (like Rooibos) should call this before entering their event loop.

pending? ()

Source

# File lib/ratatui_ruby/synthetic_events.rb, line 101
def pending?
  @mutex.synchronize { !@queue.empty? }
end

Checks for pending synthetic events.

Returns true if the queue has events waiting.

pop ()

Source

# File lib/ratatui_ruby/synthetic_events.rb, line 85
def pop
  @mutex.synchronize { @queue.shift }
end

Pops an event from the synthetic queue.

Returns the oldest pending event, or nil if empty.

push (event)

Source

# File lib/ratatui_ruby/synthetic_events.rb, line 77
def push(event)
  @mutex.synchronize { @queue << event }
end

Pushes an event to the synthetic queue.

event: An Event object (typically Event::Sync).