Module: RatatuiRuby::SyntheticEvents

Defined in:
lib/ratatui_ruby/synthetic_events.rb

Overview

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

# 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

– SPDX-SnippetEnd ++

Class Method Summary collapse

Class Method Details

.clear ⇒ Object

Clears all pending synthetic events.

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



93
94
95
 
# File 'lib/ratatui_ruby/synthetic_events.rb', line 93

def clear
  @mutex.synchronize { @queue.clear }
end

.inline_sync! ⇒ Object

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.



65
66
67
 
# File 'lib/ratatui_ruby/synthetic_events.rb', line 65

def inline_sync!
  @inline_sync = true
end

.inline_sync? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


69
70
71
 
# File 'lib/ratatui_ruby/synthetic_events.rb', line 69

def inline_sync? # :nodoc:
  @inline_sync
end

.pending? ⇒ Boolean

Checks for pending synthetic events.

Returns true if the queue has events waiting.

Returns:

  • (Boolean) 


101
102
103
 
# File 'lib/ratatui_ruby/synthetic_events.rb', line 101

def pending?
  @mutex.synchronize { !@queue.empty? }
end

.pop ⇒ Object

Pops an event from the synthetic queue.

Returns the oldest pending event, or nil if empty.



85
86
87
 
# File 'lib/ratatui_ruby/synthetic_events.rb', line 85

def pop
  @mutex.synchronize { @queue.shift }
end

.push(event) ⇒ Object

Pushes an event to the synthetic queue.

event

An Event object (typically Event::Sync).



77
78
79
 
# File 'lib/ratatui_ruby/synthetic_events.rb', line 77

def push(event)
  @mutex.synchronize { @queue << event }
end