Class: Tuile::EventQueue

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

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: EmptyQueueEvent, ErrorEvent, KeyEvent, TTYSizeEvent, Ticker

Instance Method Summary collapse

Constructor Details

#initialize(listen_for_keys: true) ⇒ EventQueue

Returns a new instance of EventQueue.

Parameters:

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

    if true, fires KeyEvent.



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

#locked? ⇒ Boolean

Returns true if this thread is running inside an event queue.

Returns:

  • (Boolean) —

    true if this thread is running inside an event queue.



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

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.

Parameters:

  • event (Object) —

    the event to post to the queue, should be frozen.

Raises:

  • (ArgumentError) 


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 {|event| ... } ⇒ 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.

Yields:

  • (event) —

    called for each posted event.

Yield Parameters:

Yield Returns:

  • (void)

Raises:

  • (ArgumentError) 


102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/tuile/event_queue.rb', line 102

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

#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.



140
141
142
143
 
# File 'lib/tuile/event_queue.rb', line 140

def stop
  @queue.clear
  post(nil)
end

#submit { ... } ⇒ 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.

Yields:

  • called from the event-loop thread.

Yield Returns:

  • (void) 


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

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

#tick(fps) {|tick| ... } ⇒ Ticker

Schedules ‘block` to fire on the event-loop thread roughly `fps` times per second, passing a 0-based monotonically increasing tick counter. Use it for animations (e.g. a `/-|` spinner in a Component::Label) or periodic UI refresh from a background task.

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.

Parameters:

  • fps (Numeric) —

    firings per second, must be positive. Fractional values are fine (‘fps: 0.5` ⇒ one tick every two seconds).

Yields:

  • (tick) —

    called on the event-loop thread each firing.

Yield Parameters:

  • tick (Integer) —

    0-based monotonically increasing counter.

Yield Returns:

  • (void)

Returns:

Raises:

  • (ArgumentError) 


73
74
75
76
77
78
79
80
 
# File 'lib/tuile/event_queue.rb', line 73

def tick(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

  Ticker.new(self, fps, block)
end