Module: Servolux::Threaded
- Included in:
- Server
- Defined in:
- lib/servolux/threaded.rb
Overview
Synopsis
The Threaded module is used to peform some activity at a specified interval.
Details
Sometimes it is useful for an object to have its own thread of execution to perform a task at a recurring interval. The Threaded module encapsulates this functionality so you don’t have to write it yourself. It can be used with any object that responds to the run
method.
The threaded object is run by calling the start
method. This will create a new thread that will invoke the run
method at the desired interval. Just before the thread is created the before_starting
method will be called (if it is defined by the threaded object). Likewise, after the thread is created the after_starting
method will be called (if it is defeined by the threaded object).
The threaded object is stopped by calling the stop
method. This sets an internal flag and then wakes up the thread. The thread gracefully exits after checking the flag. Like the start method, before and after methods are defined for stopping as well. Just before the thread is stopped the before_stopping
method will be called (if it is defined by the threaded object). Likewise, after the thread has died the after_stopping
method will be called (if it is defeined by the threaded object).
Calling the join
method on a threaded object will cause the calling thread to wait until the threaded object has stopped. An optional timeout parameter can be given.
Examples
Take a look at the Servolux::Server class for an example of a threaded object.
Defined Under Namespace
Classes: ThreadContainer
Instance Method Summary collapse
-
#_activity_thread ⇒ Object
:stopdoc:.
-
#continue_on_error=(value) ⇒ Object
Set to
true
to continue running the threaded object even if an error is raised by therun
method. -
#continue_on_error? ⇒ Boolean
Returns
true
if the threded object should continue running even if an error is raised by the run method. -
#finished_iterations? ⇒ Boolean
Returns
true
if the activity thread has finished its maximum number of iterations or the thread is no longer running. -
#interval ⇒ Object
Returns the number of seconds to sleep between invocations of the threaded object’s ‘run’ method.
-
#interval=(value) ⇒ Object
Sets the number of seconds to sleep between invocations of the threaded object’s ‘run’ method.
-
#iterations ⇒ Object
Returns the number of iterations of the threaded object’s ‘run’ method completed thus far.
-
#join(limit = nil) ⇒ Object
If the activity thread is running, the calling thread will suspend execution and run the activity thread.
-
#maximum_iterations ⇒ Object
Returns the maximum number of invocations of the threaded object’s ‘run’ method.
-
#maximum_iterations=(value) ⇒ Object
Sets the maximum number of invocations of the threaded object’s ‘run’ method.
-
#run ⇒ Object
This method will be called by the activity thread at the desired interval.
-
#running? ⇒ Boolean
Returns
true
if the activity thread is running. -
#start ⇒ Object
Start the activity thread.
-
#status ⇒ Object
Returns the status of threaded object.
-
#stop ⇒ Object
Stop the activity thread.
-
#wait(limit = nil) ⇒ Object
Wait on the activity thread.
Instance Method Details
#_activity_thread ⇒ Object
:stopdoc:
201 202 203 |
# File 'lib/servolux/threaded.rb', line 201 def _activity_thread @_activity_thread ||= ::Servolux::Threaded::ThreadContainer.new(60, 0, nil, false); end |
#continue_on_error=(value) ⇒ Object
Set to true
to continue running the threaded object even if an error is raised by the run
method. The default behavior is to stop the activity thread when an error is raised by the run method.
A SystemExit will never be caught; it will always cause the Ruby interpreter to exit.
188 189 190 |
# File 'lib/servolux/threaded.rb', line 188 def continue_on_error=( value ) _activity_thread.continue_on_error = (value ? true : false) end |
#continue_on_error? ⇒ Boolean
Returns true
if the threded object should continue running even if an error is raised by the run method. The default is to return false
. The threaded object will stop running when an error is raised.
196 197 198 |
# File 'lib/servolux/threaded.rb', line 196 def continue_on_error? _activity_thread.continue_on_error end |
#finished_iterations? ⇒ Boolean
Returns true
if the activity thread has finished its maximum number of iterations or the thread is no longer running. Returns false
otherwise.
118 119 120 121 |
# File 'lib/servolux/threaded.rb', line 118 def finished_iterations? return true unless _activity_thread.running? @_activity_thread.finished_iterations? end |
#interval ⇒ Object
Returns the number of seconds to sleep between invocations of the threaded object’s ‘run’ method.
151 152 153 |
# File 'lib/servolux/threaded.rb', line 151 def interval _activity_thread.interval end |
#interval=(value) ⇒ Object
Sets the number of seconds to sleep between invocations of the threaded object’s ‘run’ method.
142 143 144 145 146 |
# File 'lib/servolux/threaded.rb', line 142 def interval=( value ) value = Float(value) raise ArgumentError, "Sleep interval must be >= 0" unless value >= 0 _activity_thread.interval = value end |
#iterations ⇒ Object
Returns the number of iterations of the threaded object’s ‘run’ method completed thus far.
177 178 179 |
# File 'lib/servolux/threaded.rb', line 177 def iterations _activity_thread.iterations end |
#join(limit = nil) ⇒ Object
If the activity thread is running, the calling thread will suspend execution and run the activity thread. This method does not return until the activity thread is stopped or until limit seconds have passed.
If the activity thread is not running, this method returns immediately with nil
.
103 104 105 |
# File 'lib/servolux/threaded.rb', line 103 def join( limit = nil ) _activity_thread.join(limit) ? self : nil end |
#maximum_iterations ⇒ Object
Returns the maximum number of invocations of the threaded object’s ‘run’ method
170 171 172 |
# File 'lib/servolux/threaded.rb', line 170 def maximum_iterations _activity_thread.maximum_iterations end |
#maximum_iterations=(value) ⇒ Object
Sets the maximum number of invocations of the threaded object’s ‘run’ method
158 159 160 161 162 163 164 165 |
# File 'lib/servolux/threaded.rb', line 158 def maximum_iterations=( value ) unless value.nil? value = Integer(value) raise ArgumentError, "maximum iterations must be >= 1" unless value >= 1 end _activity_thread.maximum_iterations = value end |
#run ⇒ Object
This method will be called by the activity thread at the desired interval. Implementing classes are exptect to provide this functionality.
41 42 43 44 |
# File 'lib/servolux/threaded.rb', line 41 def run raise NotImplementedError, 'The run method must be defined by the threaded object.' end |
#running? ⇒ Boolean
Returns true
if the activity thread is running. Returns false
otherwise.
110 111 112 |
# File 'lib/servolux/threaded.rb', line 110 def running? _activity_thread.running? end |
#start ⇒ Object
Start the activity thread. If already started this method will return without taking any action.
If the including class defines a ‘before_starting’ method, it will be called before the thread is created and run. Likewise, if the including class defines an ‘after_starting’ method, it will be called after the thread is created.
54 55 56 57 58 59 60 61 62 |
# File 'lib/servolux/threaded.rb', line 54 def start return self if _activity_thread.running? logger.debug "Starting" before_starting if self.respond_to?(:before_starting) @_activity_thread.start self after_starting if self.respond_to?(:after_starting) self end |
#status ⇒ Object
Returns the status of threaded object.
'sleep' : sleeping or waiting on I/O
'run' : executing
'aborting' : aborting
false : not running or terminated normally
nil : terminated with an exception
If this method returns nil
, then calling join on the threaded object will cause the exception to be raised in the calling thread.
134 135 136 137 |
# File 'lib/servolux/threaded.rb', line 134 def status return false if _activity_thread.thread.nil? @_activity_thread.thread.status end |
#stop ⇒ Object
Stop the activity thread. If already stopped this method will return without taking any action.
If the including class defines a ‘before_stopping’ method, it will be called before the thread is stopped. Likewise, if the including class defines an ‘after_stopping’ method, it will be called after the thread has stopped.
72 73 74 75 76 77 78 79 |
# File 'lib/servolux/threaded.rb', line 72 def stop return self unless _activity_thread.running? logger.debug "Stopping" before_stopping if self.respond_to?(:before_stopping) @_activity_thread.stop self end |
#wait(limit = nil) ⇒ Object
Wait on the activity thread. If the thread is already stopped, this method will return without taking any action. Otherwise, this method does not return until the activity thread has stopped, or a specific number of iterations has passed since this method was called.
86 87 88 89 90 91 92 93 94 |
# File 'lib/servolux/threaded.rb', line 86 def wait( limit = nil ) return self unless _activity_thread.running? initial_iterations = @_activity_thread.iterations loop { break unless @_activity_thread.running? break if limit and @_activity_thread.iterations > ( initial_iterations + limit ) Thread.pass } end |