Module: DirectoryWatcher::Threaded

### Home Classes Methods

### In Files

- lib/directory_watcher/threaded.rb

### Methods

- #continue_on_error=
- #continue_on_error?
- #finished_iterations?
- #interval
- #interval=
- #iterations
- #join
- #maximum_iterations
- #maximum_iterations=
- #pause
- #resume
- #run
- #running?
- #start
- #status
- #stop
- #wait

### Files

- History.txt
- README.txt

### Class/Module Index

Quicksearch

- DirectoryWatcher
- DirectoryWatcher::Collector
- DirectoryWatcher::Configuration
- DirectoryWatcher::CoolioScanner
- DirectoryWatcher::EmScanner
- DirectoryWatcher::Event
- DirectoryWatcher::EventableScanner
- DirectoryWatcher::FileStat
- DirectoryWatcher::Logable
- DirectoryWatcher::Notifier
- DirectoryWatcher::NullLogger
- DirectoryWatcher::Paths
- DirectoryWatcher::RevScanner
- DirectoryWatcher::Scan
- DirectoryWatcher::ScanAndQueue
- DirectoryWatcher::Scanner
- DirectoryWatcher::Threaded
- DirectoryWatcher::Version
- Object

No matching classes.

# 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

continue_on_error=( value ) click to toggle source

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

continue_on_error?() click to toggle source

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

finished_iterations?() click to toggle source

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

interval() click to toggle source

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

interval=( value ) click to toggle source

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

iterations() click to toggle source

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

join( limit = nil ) click to toggle source

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

maximum_iterations() click to toggle source

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

maximum_iterations=( value ) click to toggle source

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

pause() click to toggle source

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() click to toggle source

Resume the activity thread

    # File lib/directory_watcher/threaded.rb, line 83
    def resume
      @_activity_thread.working = true
    end

run() click to toggle source

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

running?() click to toggle source

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() click to toggle source

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

status() click to toggle source

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() click to toggle source

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( limit = nil ) click to toggle source

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

[Validate]

Generated with the Darkfish Rdoc Generator 2.