Class: Lowdown::Threading::Consumer

Inherits:
Object
  • Object
show all
Defined in:
lib/lowdown/threading.rb

Overview

This class performs jobs on a private thread, provides lifecycle callbacks, and sends exceptions onto its parent thread.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(queue: Thread::Queue.new, parent_thread: Thread.current) ⇒ Consumer

Returns a new instance of Consumer.

Parameters:

  • queue (Thread::Queue) (defaults to: Thread::Queue.new) —

    a queue instance. Provide a Thread::SizedQueue if you want queue of a max size.

  • parent_thread (Thread) (defaults to: Thread.current) —

    the thread to send exceptions to.



17
18
19
20
 
# File 'lib/lowdown/threading.rb', line 17

def initialize(queue: Thread::Queue.new, parent_thread: Thread.current)
  @queue, @parent_thread = queue, parent_thread
  @thread = Thread.new(&method(:main))
end

Instance Attribute Details

#parent_thread ⇒ Thread (readonly, protected)

Returns the thread to send exceptions to.

Returns:

  • (Thread) —

    the thread to send exceptions to.



62
63
64
 
# File 'lib/lowdown/threading.rb', line 62

def parent_thread
  @parent_thread
end

#queue ⇒ Thread::Queue (readonly, protected)

Returns the jobs queue.

Returns:

  • (Thread::Queue) —

    the jobs queue.



67
68
69
 
# File 'lib/lowdown/threading.rb', line 67

def queue
  @queue
end

#thread ⇒ Thread (readonly, protected)

Returns the private thread.

Returns:

  • (Thread) —

    the private thread.



57
58
59
 
# File 'lib/lowdown/threading.rb', line 57

def thread
  @thread
end

Instance Method Details

#alive? ⇒ Boolean

Returns whether or not the private thread is still alive.

Returns:

  • (Boolean) —

    whether or not the private thread is still alive.



41
42
43
 
# File 'lib/lowdown/threading.rb', line 41

def alive?
  thread.alive?
end

#empty? ⇒ Boolean

Returns whether or not there are any scheduled jobs left in the queue.

Returns:

  • (Boolean) —

    whether or not there are any scheduled jobs left in the queue.



48
49
50
 
# File 'lib/lowdown/threading.rb', line 48

def empty?
  queue.empty?
end

#enqueue(&job) ⇒ void

This method returns an undefined value.

Schedules a job to be performed.



26
27
28
 
# File 'lib/lowdown/threading.rb', line 26

def enqueue(&job)
  queue << job
end

#kill ⇒ void

This method returns an undefined value.

Kills the private thread.



34
35
36
 
# File 'lib/lowdown/threading.rb', line 34

def kill
  thread.kill
end

#main ⇒ void (protected)

Note:

This method is ran on the private thread.

This method returns an undefined value.

This represents the full lifecycle of the consumer thread. It performs the individual events, catches uncaught exceptions and sends those to the parent thread, and performs cleanup.

Subclasses should override the individual events.



78
79
80
81
82
83
84
85
 
# File 'lib/lowdown/threading.rb', line 78

def main
  pre_runloop
  runloop
rescue Exception => exception
  parent_thread.raise(exception)
ensure
  post_runloop
end

#perform_job(non_block:, arguments: nil) ⇒ void (protected)

This method returns an undefined value.

Parameters:

  • non_block (Boolean) —

    whether or not the thread should be halted if there are no jobs to perform.

  • arguments (Array<Object>) (defaults to: nil) —

    arguments that should be passed to the invoked job.



127
128
129
130
 
# File 'lib/lowdown/threading.rb', line 127

def perform_job(non_block:, arguments: nil)
  queue.pop(non_block).call(*arguments)
rescue ThreadError
end

#post_runloop ⇒ void (protected)

Note:

This method is ran on the private thread.

This method returns an undefined value.

Ran when the thread is killed or an uncaught exception occurred.

This kills the consumer thread, which means that any cleanup you need to perform should be done before calling this super implementation.



115
116
117
 
# File 'lib/lowdown/threading.rb', line 115

def post_runloop
  thread.kill
end

#pre_runloop ⇒ void (protected)

Note:

This method is ran on the private thread.

This method returns an undefined value.

Ran before any jobs are performed.



93
94
 
# File 'lib/lowdown/threading.rb', line 93

def pre_runloop
end

#runloop ⇒ void (protected)

Note:

This method is ran on the private thread.

This method returns an undefined value.

The loop that performs scheduled jobs.



102
103
104
 
# File 'lib/lowdown/threading.rb', line 102

def runloop
  loop { perform_job(non_block: false) }
end