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 73
def clear
  @mutex.synchronize { @queue.clear }
end

Clears all pending synthetic events.

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

pending? ()

Source

# File lib/ratatui_ruby/synthetic_events.rb, line 81
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 65
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 57
def push(event)
  @mutex.synchronize { @queue << event }
end

Pushes an event to the synthetic queue.

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