module DirectoryWatcher::Threaded
Synopsis¶ ↑
The Threaded module is used to perform 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 defined 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 defined 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.
Public Instance Methods
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.
# File lib/directory_watcher/threaded.rb, line 194 def continue_on_error=( value ) _activity_thread.continue_on_error = (value ? true : false) end
Returns true
if the threaded 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.
# File lib/directory_watcher/threaded.rb, line 202 def continue_on_error? _activity_thread.continue_on_error end
Returns true
if the activity thread has finished its maximum
number of iterations or the thread is no longer running. Returns
false
otherwise.
# File lib/directory_watcher/threaded.rb, line 124 def finished_iterations? return true unless _activity_thread.running? @_activity_thread.finished_iterations? end
Returns the number of seconds to sleep between invocations of the threaded object's 'run' method.
# File lib/directory_watcher/threaded.rb, line 157 def interval _activity_thread.interval end
Sets the number of seconds to sleep between invocations of the threaded object's 'run' method.
# File lib/directory_watcher/threaded.rb, line 148 def interval=( value ) value = Float(value) raise ArgumentError, "Sleep interval must be >= 0" unless value >= 0 _activity_thread.interval = value end
Returns the number of iterations of the threaded object's 'run' method completed thus far.
# File lib/directory_watcher/threaded.rb, line 183 def iterations _activity_thread.iterations end
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
.
# File lib/directory_watcher/threaded.rb, line 109 def join( limit = nil ) _activity_thread.join(limit) ? self : nil end
Returns the maximum number of invocations of the threaded object's 'run' method
# File lib/directory_watcher/threaded.rb, line 176 def maximum_iterations _activity_thread.maximum_iterations end
Sets the maximum number of invocations of the threaded object's 'run' method
# File lib/directory_watcher/threaded.rb, line 164 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
Stop the activity thread from doing work. This will not stop the activity thread, it will just stop it from calling the 'run' method on every iteration. It will also not increment the number of iterations it has run.
# File lib/directory_watcher/threaded.rb, line 78 def pause @_activity_thread.working = false end
Resume the activity thread
# File lib/directory_watcher/threaded.rb, line 83 def resume @_activity_thread.working = true end
This method will be called by the activity thread at the desired interval. Implementing classes are expect to provide this functionality.
# File lib/directory_watcher/threaded.rb, line 37 def run raise NotImplementedError, 'The run method must be defined by the threaded object.' end
Returns true
if the activity thread is running. Returns
false
otherwise.
# File lib/directory_watcher/threaded.rb, line 116 def running? _activity_thread.running? end
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.
# File lib/directory_watcher/threaded.rb, line 50 def start return self if _activity_thread.running? before_starting if self.respond_to?(:before_starting) @_activity_thread.start self after_starting if self.respond_to?(:after_starting) self end
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.
# File lib/directory_watcher/threaded.rb, line 140 def status return false if _activity_thread.thread.nil? @_activity_thread.thread.status end
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.
# File lib/directory_watcher/threaded.rb, line 67 def stop return self unless _activity_thread.running? before_stopping if self.respond_to?(:before_stopping) @_activity_thread.stop self end
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.
# File lib/directory_watcher/threaded.rb, line 92 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