class DirectoryWatcher

Synopsis¶ ↑

A class for watching files within a directory and generating events when those files change.

Details¶ ↑

A directory watcher is an Observable object that sends events to registered observers when file changes are detected within the directory being watched.

The directory watcher operates by scanning the directory at some interval and creating a list of the files it finds. File events are detected by comparing the current file list with the file list from the previous scan interval. Three types of events are supported – added, modified, and

removed*.

An added event is generated when the file appears in the current file list but not in the previous scan interval file list. A removed event is generated when the file appears in the previous scan interval file list but not in the current file list. A modified event is generated when the file appears in the current and the previous interval file list, but the file modification time or the file size differs between the two lists.

The file events are collected into an array, and all registered observers receive all file events for each scan interval. It is up to the individual observers to filter the events they are interested in.

File Selection¶ ↑

The directory watcher uses glob patterns to select the files to scan. The default glob pattern will select all regular files in the directory of interest '*'.

Here are a few useful glob examples:

   '*'               => all files in the current directory
   '**  '            => all files in all subdirectories
   '   *.rb'         => all ruby files
   'ext   /*.{h,c}'  => all C source code files

Note*: file events will never be generated for directories. Only regular

files are included in the file scan.

Stable Files¶ ↑

A fourth file event is supported but not enabled by default – the

stable* event. This event is generated after a file has been added or

modified and then remains unchanged for a certain number of scan intervals.

To enable the generation of this event the stable count must be configured. This is the number of scan intervals a file must remain unchanged (based modification time and file size) before it is considered stable.

To disable this event the stable count should be set to nil.

Usage¶ ↑

Learn by Doing – here are a few different ways to configure and use a directory watcher.

Basic¶ ↑

This basic recipe will watch all files in the current directory and generate the three default events. We'll register an observer that simply prints the events to standard out.

require 'directory_watcher'

dw = DirectoryWatcher.new '.'
dw.add_observer {|*args| args.each {|event| puts event}}

dw.start
gets      # when the user hits "enter" the script will terminate
dw.stop

Suppress Initial “added” Events¶ ↑

This little twist will suppress the initial “added” events that are generated the first time the directory is scanned. This is done by pre-loading the watcher with files – i.e. telling the watcher to scan for files before actually starting the scan loop.

require 'directory_watcher'

dw = DirectoryWatcher.new '.', :pre_load => true
dw.glob = '   *.rb'
dw.add_observer {|*args| args.each {|event| puts event}}

dw.start
gets      # when the user hits "enter" the script will terminate
dw.stop

There is one catch with this recipe. The glob pattern must be specified before the pre-load takes place. The glob pattern can be given as an option to the constructor:

dw = DirectoryWatcher.new '.', :glob => '**/*.rb', :pre_load => true

The other option is to use the reset method:

dw = DirectoryWatcher.new '.'
dw.glob = '**/*.rb'
dw.reset true     # the +true+ flag causes the watcher to pre-load
                  # the files

Generate “stable” Events¶ ↑

In order to generate stable events, the stable count must be specified. In this example the interval is set to 5.0 seconds and the stable count is set to 2. Stable events will only be generated for files after they have remain unchanged for 10 seconds (5.0 * 2).

require 'directory_watcher'

dw = DirectoryWatcher.new '.', :glob => '**/*.rb'
dw.interval = 5.0
dw.stable = 2
dw.add_observer {|*args| args.each {|event| puts event}}

dw.start
gets      # when the user hits "enter" the script will terminate
dw.stop

Persisting State¶ ↑

A directory watcher can be configured to persist its current state to a file when it is stopped and to load state from that same file when it starts. Setting the persist value to a filename will enable this feature.

require 'directory_watcher'

dw = DirectoryWatcher.new '.', :glob => '**/*.rb'
dw.interval = 5.0
dw.persist = "dw_state.yml"
dw.add_observer {|*args| args.each {|event| puts event}}

dw.start  # loads state from dw_state.yml
gets      # when the user hits "enter" the script will terminate
dw.stop   # stores state to dw_state.yml

Running Once¶ ↑

Instead of using the built in run loop, the directory watcher can be run one or many times using the run_once method. The state of the directory watcher can be loaded and dumped if so desired.

dw = DirectoryWatcher.new '.', :glob => '**/*.rb'
dw.persist = "dw_state.yml"
dw.add_observer {|*args| args.each {|event| puts event}}

dw.load!       # loads state from dw_state.yml
dw.run_once
sleep 5.0
dw.run_once
dw.persist!    # stores state to dw_state.yml

Ordering of Events¶ ↑

In the case, particularly in the initial scan, or in cases where the Scanner may be doing a large pass over the monitored locations, many events may be generated all at once. In the default case, these will be emitted in the order in which they are observed, which tends to be alphabetical, but it not guaranteed. If you wish the events to be order by modified time, or file size this may be done by setting the sort_by and/or the order_by options.

dw = DirectoryWatcher.new '.', :glob => '**/*.rb', :sort_by => :mtime
dw.add_observer {|*args| args.each {|event| puts event}}
dw.start
gets      # when the user hits "enter" the script will terminate
dw.stop

Scanning Strategies¶ ↑

By default DirectoryWatcher uses a thread that scans the directory being watched for files and calls “stat” on each file. The stat information is used to determine which files have been modified, added, removed, etc. This approach is fairly intensive for short intervals and/or directories with many files.

DirectoryWatcher supports using Cool.io, EventMachine, or Rev instead of a busy polling thread. These libraries use system level kernel hooks to receive notifications of file system changes. This makes DirectoryWorker much more efficient.

This example will use Cool.io to generate file notifications.

dw = DirectoryWatcher.new '.', :glob => '**/*.rb', :scanner => :coolio
dw.add_observer {|*args| args.each {|event| puts event}}

dw.start
gets      # when the user hits "enter" the script will terminate
dw.stop

The scanner cannot be changed after the DirectoryWatcher has been created. To use an EventMachine scanner, pass :em as the :scanner option.

If you wish to use the Cool.io scanner, then you must have the Cool.io gem installed. The same goes for EventMachine and Rev. To install any of these gems run the following on the command line:

gem install cool.io
gem install eventmachine
gem install rev

Note: Rev has been replace by Cool.io and support for the Rev scanner will eventually be dropped from DirectoryWatcher.

Contact¶ ↑

A lot of discussion happens about Ruby in general on the ruby-talk mailing list (www.ruby-lang.org/en/ml.html), and you can ask any questions you might have there. I monitor the list, as do many other helpful Rubyists, and you're sure to get a quick answer. Of course, you're also welcome to email me (Tim Pease) directly at the at tim.pease@gmail.com, and I'll do my best to help you out.

(the above paragraph was blatantly stolen from Nathaniel Talbott's Test::Unit documentation)

Author¶ ↑

Tim Pease