Class: Tuile::EventQueue

Inherits:
Object
  • Object
show all
Defined in:
lib/tuile/event_queue.rb,
sig/tuile.rbs

Overview

An event queue. The idea is that all UI-related updates run from the thread which runs the event queue only; this removes any need for locking and/or need for thread-safety mechanisms.

Any events (keypress, timer, term resize – WINCH) are captured in background threads; instead of processing the events directly the events are pushed into the event queue: this causes the events to be processed centrally, by a single thread only.

Defined Under Namespace

Classes: ColorSchemeEvent, EmptyQueueEvent, ErrorEvent, KeyEvent, TTYSizeEvent, Ticker

Instance Method Summary collapse

Constructor Details

#initialize(listen_for_keys: true) ⇒ EventQueue

@param listen_for_keys — if true, fires KeyEvent.

Parameters:

  • listen_for_keys: (Boolean) (defaults to: true) 


14
15
16
17
18
 
# File 'lib/tuile/event_queue.rb', line 14

def initialize(listen_for_keys: true)
  @queue = Thread::Queue.new
  @listen_for_keys = listen_for_keys
  @run_lock = Mutex.new
end

Instance Method Details

#await_empty ⇒ void

This method returns an undefined value.

Awaits until the event queue is empty (all events have been processed).



44
45
46
47
48
 
# File 'lib/tuile/event_queue.rb', line 44

def await_empty
  latch = Concurrent::CountDownLatch.new(1)
  submit { latch.count_down }
  latch.wait
end

#event_loop ⇒ void

This method returns an undefined value.



301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
 
# File 'lib/tuile/event_queue.rb', line 301

def event_loop
  loop do
    yield EmptyQueueEvent.instance if @queue.empty?
    event = @queue.pop
    break if event.nil?

    if event.is_a? ErrorEvent
      begin
        raise event.error
      rescue StandardError
        # Re-raise wrapped so the original error is preserved as `cause`
        # while the loop's own backtrace shows up in the wrapper.
        raise Tuile::Error, "background event raised: #{event.error.class}: #{event.error.message}"
      end
    else
      yield event
    end
  end
end

#locked? ⇒ Boolean

@return — true if this thread is running inside an event queue.

Returns:

  • (Boolean) 


153
 
# File 'lib/tuile/event_queue.rb', line 153

def locked? = @run_lock.owned?

#post(event) ⇒ void

This method returns an undefined value.

Posts event into the event queue. The event may be of any type. Since the event is passed between threads, the event object should be frozen.

The function may be called from any thread.

@param event — the event to post to the queue, should be frozen.

Parameters:

  • event (Object) 


26
27
28
29
30
 
# File 'lib/tuile/event_queue.rb', line 26

def post(event)
  raise ArgumentError, "event passed across threads must be frozen, got #{event.inspect}" unless event.frozen?

  @queue << event
end

#run_loop ⇒ void

This method returns an undefined value.

Runs the event loop and blocks. Must be run from at most one thread at the same time. Blocks until some thread calls #stop. Calls block for all events; the block is always called from the thread running this function.

Any exception raised by the block is re-thrown, causing this function to terminate. Wrap the block body in rescue if you want to handle errors without tearing down the loop — see Screen#event_loop for an example.

Procs are yielded too. A #submited block arrives as a Proc event; the consumer is responsible for invoking it (typically event.call). Yielding rather than dispatching inline means a raise inside the submitted block flows through the consumer's rescue like any other event-handler error, instead of bypassing it.



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/tuile/event_queue.rb', line 123

def run_loop(&)
  raise ArgumentError, "run_loop requires a block" unless block_given?

  @run_lock.synchronize do
    start_key_thread if @listen_for_keys
    begin
      trap_winch
      event_loop(&)
    ensure
      Signal.trap("WINCH", "SYSTEM_DEFAULT")
      if @key_thread
        # Kill returns immediately, but the key thread is typically
        # blocked inside $stdin.getch with a termios snapshot saved in
        # io-console's C-level ensure. If we let it run to completion
        # *after* the outer $stdin.raw block has exited (e.g. when an
        # exception is escaping run_event_loop), the late tcsetattr
        # restores raw mode and leaves the terminal with ONLCR off —
        # the stack trace then prints as one un-wrapped soft line.
        # Joining here forces the restore to happen while we're still
        # nested inside $stdin.raw, so raw's own restoration is the
        # final write and the terminal lands in cooked mode.
        @key_thread.kill
        @key_thread.join
      end
      @queue.clear
    end
  end
end

#start_key_thread ⇒ void

This method returns an undefined value.

Starts listening for stdin, firing KeyEvent on keypress.



323
324
325
326
327
328
329
330
331
332
333
 
# File 'lib/tuile/event_queue.rb', line 323

def start_key_thread
  @key_thread = Thread.new do
    loop do
      key = Keys.getkey
      event = MouseEvent.parse(key) || ColorSchemeEvent.parse(key) || KeyEvent.new(key)
      post event
    end
  rescue StandardError => e
    post ErrorEvent.new(e)
  end
end

#stop ⇒ void

This method returns an undefined value.

Stops ongoing #run_loop. The stop may not be immediate: #run_loop may process a bunch of events before terminating.

Can be called from any thread, including the thread which runs the event loop.



161
162
163
164
 
# File 'lib/tuile/event_queue.rb', line 161

def stop
  @queue.clear
  post(nil)
end

#submit(&block) ⇒ void

This method returns an undefined value.

Submits block to be run in the event queue. Returns immediately.

The function may be called from any thread.



38
39
40
 
# File 'lib/tuile/event_queue.rb', line 38

def submit(&block)
  @queue << block
end

#tick(seconds, &block) ⇒ void

This method returns an undefined value.

Schedules block to fire on the event-loop thread every seconds, passing a 0-based monotonically increasing tick counter. The interval is in seconds — the conventional scheduling unit (sleep, Concurrent::TimerTask#execution_interval, …) — so tick(0.2) fires five times a second. Use it for periodic UI refresh from a background task (poll a status, redraw a clock). For animation, where frames-per-second is the natural unit, #tick_fps reads better.

The returned Ticker controls the schedule — call Tuile::EventQueue::Ticker#cancel to stop it.

Errors: if block raises, the Ticker cancels itself and the exception flows through the normal event-loop error path — i.e. Screen#on_error for the default Tuile setup. Auto-cancel prevents a broken block from spamming on_error at the tick rate.

Tickers reuse concurrent-ruby's shared timer thread (Concurrent.global_timer_set) — adding more tickers does not add more threads, just more work on the shared scheduler.

@param seconds — interval between firings, must be positive. Fractional values are fine (tick(0.05) ⇒ ~20 firings a second).

Parameters:

  • seconds (Numeric) 


76
77
78
79
80
81
82
83
 
# File 'lib/tuile/event_queue.rb', line 76

def tick(seconds, &block)
  raise ArgumentError, "block required" unless block
  unless seconds.is_a?(Numeric) && seconds.positive?
    raise ArgumentError, "seconds must be a positive Numeric, got #{seconds.inspect}"
  end

  Ticker.new(self, seconds, block)
end

#tick_fps(fps, &block) ⇒ void

This method returns an undefined value.

Frames-per-second convenience over #tick: tick_fps(15) is exactly tick(1.0 / 15). Reads naturally for animation (a /-\| spinner, a progress pulse) where you think in frames, not intervals.

@param fps — firings per second, must be positive. Fractional values are fine (tick_fps(0.5) ⇒ one firing every two seconds).

Parameters:

  • fps (Numeric) 


94
95
96
97
98
99
100
101
 
# File 'lib/tuile/event_queue.rb', line 94

def tick_fps(fps, &block)
  raise ArgumentError, "block required" unless block
  unless fps.is_a?(Numeric) && fps.positive?
    raise ArgumentError, "fps must be a positive Numeric, got #{fps.inspect}"
  end

  tick(1.0 / fps, &block)
end

#trap_winch ⇒ void

This method returns an undefined value.

Trap the WINCH signal (TTY resize signal) and fire TTYSizeEvent.



337
338
339
340
341
342
343
 
# File 'lib/tuile/event_queue.rb', line 337

def trap_winch
  Signal.trap("WINCH") do
    post TTYSizeEvent.create
  rescue StandardError => e
    post ErrorEvent.new(e)
  end
end