sinotify 0.0.2

data/lib/sinotify_info.rb

@@ -0,0 +1,47 @@
+module Sinotify
+
+  VERSION = '0.0.2'
+
+  # :stopdoc:
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+  # :startdoc:
+
+end  # module Sinotify
+

data/sinotify.gemspec

@@ -0,0 +1,80 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{sinotify}
+  s.version = "0.0.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Steven Swerling"]
+  s.date = %q{2009-08-09}
+  s.description = %q{ALPHA Alert -- just uploaded initial release. 
+
+Linux inotify is a means to receive events describing file system activity (create, modify, delete, close, etc). 
+
+Sinotify was derived from aredridel's package (http://raa.ruby-lang.org/project/ruby-inotify/), with the addition of
+Paul Boon's tweak for making the event_check thread more polite (see
+http://www.mindbucket.com/2009/02/24/ruby-daemons-verifying-good-behavior/)
+
+In sinotify, the classes Sinotify::PrimNotifier and Sinotify::PrimEvent provide a low level wrapper to inotify, with
+the ability to establish 'watches' and then listen for inotify events using one of inotify's synchronous event loops,
+and providing access to the events' masks (see 'man inotify' for details). Sinotify::PrimEvent class adds a little semantic sugar
+to the event in to the form of 'etypes', which are just ruby symbols that describe the event mask. If the event has a
+raw mask of (DELETE_SELF & IS_DIR), then the etypes array would be [:delete_self, :is_dir]. 
+
+In addition to the 'straight' wrapper in inotify, sinotify provides an asynchronous implementation of the 'observer
+pattern' for notification. In other words, Sinotify::Notifier listens in the background for inotify events, adapting
+them into instances of Sinotify::Event as they come in and immediately placing them in a concurrent queue, from which
+they are 'announced' to 'subscribers' of the event.  [Sinotify uses the 'cosell' implementation of the Announcements
+event notification framework, hence the terminology 'subscribe' and 'announce' rather then 'listen' and 'trigger' used
+in the standard event observer pattern. See the 'cosell' package on github for details.]
+
+A variety of 'knobs' are provided for controlling the behavior of the notifier: whether a watch should apply to a
+single directory or should recurse into subdirectores, how fast it should broadcast queued events, etc (see
+Sinotify::Notifier, and the example in the synopsis section below). An event 'spy' can also be setup to log all
+Sinotify::PrimEvents and Sinotify::Events.
+
+Sinotify::Event simplifies inotify's muddled event model, sending events only for those files/directories that have
+changed. That's not to say you can't setup a notifier that recurses into subdirectories, just that any individual
+event will apply to a single file, and not to its children. Also, event types are identified using words (in the form
+of ruby :symbols) instead of inotify's event masks. See Sinotify::Event for more explanation. 
+
+The README for inotify:
+
+  http://www.kernel.org/pub/linux/kernel/people/rml/inotify/README
+
+Selected quotes from the README for inotify:
+
+  * "Rumor is that the 'd' in 'dnotify' does not stand for 'directory' but for 'suck.'"
+
+  * "The 'i' in inotify does not stand for 'suck' but for 'inode' -- the logical
+    choice since inotify is inode-based."
+  
+(The 's' in 'sinotify' does in fact stand for 'suck.')}
+  s.email = %q{sswerling@yahoo.com}
+  s.extensions = ["ext/extconf.rb"]
+  s.extra_rdoc_files = ["History.txt", "README.txt"]
+  s.files = [".gitignore", "History.txt", "README.rdoc", "README.txt", "Rakefile", "TODO", "examples/watcher.rb", "ext/extconf.rb", "ext/src/inotify-syscalls.h", "ext/src/inotify.h", "ext/src/sinotify.c", "lib/sinotify.rb", "lib/sinotify/event.rb", "lib/sinotify/notifier.rb", "lib/sinotify/prim_event.rb", "lib/sinotify/watch.rb", "lib/sinotify_info.rb", "sinotify.gemspec", "spec/prim_notify_spec.rb", "spec/sinotify_spec.rb", "spec/spec_helper.rb"]
+  s.has_rdoc = true
+  s.homepage = %q{http://tab-a.slot-z.net}
+  s.rdoc_options = ["--inline-source", "--main", "README.txt"]
+  s.require_paths = ["lib", "ext"]
+  s.rubyforge_project = %q{sinotify}
+  s.rubygems_version = %q{1.3.2}
+  s.summary = %q{ALPHA Alert -- just uploaded initial release}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<cosell>, [">= 0"])
+      s.add_development_dependency(%q<bones>, [">= 2.5.1"])
+    else
+      s.add_dependency(%q<cosell>, [">= 0"])
+      s.add_dependency(%q<bones>, [">= 2.5.1"])
+    end
+  else
+    s.add_dependency(%q<cosell>, [">= 0"])
+    s.add_dependency(%q<bones>, [">= 2.5.1"])
+  end
+end

data/spec/prim_notify_spec.rb

@@ -0,0 +1,98 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+require 'fileutils'
+
+#
+# The tests for the inotify wrapper. 
+# Mostly taken straight from ruby-inotify's tests, w/ some tweaks.
+#
+describe Sinotify::PrimNotifier do
+
+  before(:each) do
+    @inotify = Sinotify::PrimNotifier.new
+  end
+
+  it "should be able to create and remove a watch descriptor" do
+    wd =  @inotify.add_watch("/tmp", Sinotify::PrimEvent::CREATE)
+    wd.class.should be_eql(Fixnum)
+    wd.should_not be_eql(0)
+    @inotify.rm_watch(wd).should be_true
+  end
+
+  it "should get events on watched directory and get name of altered file in watched directory" do
+    test_fn = "/tmp/sinotify-test"
+    FileUtils.rm_f test_fn 
+    wd = @inotify.add_watch("/tmp", Sinotify::PrimEvent::DELETE | Sinotify::PrimEvent::CREATE)
+    begin 
+      FileUtils.touch test_fn
+      @inotify.each_event do |ev|
+        #puts "-----------#{ev.etypes.inspect}"
+        ev.class.should be_eql(Sinotify::PrimEvent)
+        ev.name.should be_eql('sinotify-test')
+        ev.mask.should be_eql(Sinotify::PrimEvent::CREATE)
+        ev.has_etype?(:create).should be_true
+        ev.etypes.size.should be_eql(1) 
+        ev.inspect.should be_eql "<Sinotify::PrimEvent :name => 'sinotify-test', :etypes => [:create], :mask => 100, :watch_descriptor => 1>"
+        break
+      end
+      FileUtils.rm_f test_fn
+      @inotify.each_event do |ev|
+        #puts "-----------#{ev.etypes.inspect}"
+        ev.has_etype?(:delete).should be_true
+        ev.etypes.size.should be_eql(1) 
+        break
+      end
+    ensure
+      @inotify.rm_watch(wd)
+      FileUtils.rm_f test_fn 
+    end
+  end
+
+  it "should get events on watched file" do
+    test_fn = "/tmp/sinotify-test"
+    FileUtils.touch test_fn 
+    wd = @inotify.add_watch(test_fn, Sinotify::PrimEvent::ATTRIB | Sinotify::PrimEvent::DELETE | Sinotify::PrimEvent::MODIFY)
+    begin 
+      FileUtils.touch test_fn
+      @inotify.each_event do |ev|
+        ev.name.should be_nil # name is only set when watching a directory
+        ev.has_etype?(:attrib).should be_true
+        break
+      end
+
+      File.open(test_fn, 'a'){|f| f << 'hi'}
+      @inotify.each_event do |ev|
+        ev.name.should be_nil # name is only set when watching a directory
+        ev.has_etype?(:modify).should be_true
+        break
+      end
+
+      FileUtils.rm_f test_fn
+      @inotify.each_event do |ev|
+        #puts "-----------#{ev.inspect}"
+        # TODO: Look into this -- when deleting a file, it gets an event of type :attrib instead of :delete.
+        # Is this a bug or something I am doing?
+        # ev.has_etype?(:delete).should be_true
+        break
+      end
+
+      # since the event is deleted, it should not be possible to remove the watch
+      lambda{@inotify.rm_watch(wd)}.should raise_error
+
+    ensure
+      @inotify.rm_watch(wd) rescue nil
+      FileUtils.rm_f test_fn 
+    end
+  end
+
+  protected
+
+    def little_bench(msg, &block)
+      start = Time.now
+      result = block.call
+      puts "#{msg}: #{Time.now - start} sec"
+      return result
+    end
+end
+
+# EOF
+

data/spec/sinotify_spec.rb

@@ -0,0 +1,265 @@
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+require 'fileutils'
+
+class MockPrimEvent
+  attr_accessor :etypes, :mask, :wd, :name
+end
+
+#
+#  WARNING: These tests are a bit brittle. They depend on events taking place in threads as a result
+#  of filesytem events (inotify events). Sometimes the file system events dont come in as fast as
+#  desirable for the test, or sometimes ruby threads themselves may not get scheduled fast enough.
+#  If a test is failing on your system, it may start to succeed if you increase the values
+#  in tiny_pause!, pause!, or big_pause! methods below. 
+#
+describe Sinotify do
+
+  # A lot of Sinotify work occurs in background threads (eg. adding watches, adding subdirectories),
+  # so the tests may insert a tiny pauses to allow the bg threads to do their thing before making
+  # any assertions. 
+  def tiny_pause!
+    25.times{sleep 0.0001}
+  end
+  def pause!
+    25.times{sleep 0.005}
+  end
+  def big_pause!
+    10.times{sleep 0.1}
+  end
+
+  def reset_test_dir!
+    raise 'not gonna happen' unless @test_root_dir =~ /\/tmp\//
+    FileUtils.rm_rf(@test_root_dir)
+    FileUtils.mkdir(@test_root_dir)
+    ('a'..'z').each{|ch| FileUtils.mkdir(File.join(@test_root_dir, ch))}
+    pause!
+  end
+
+  before(:each) do
+    @test_root_dir = '/tmp/sinotifytestdir'
+  end
+
+  it "should properly create event mask from etypes" do
+    notifier = Sinotify::Notifier.new('/tmp', :recurse => false, :etypes => [:create, :modify])
+
+    #decided to make raw_mask private: notifier.raw_mask.should be_eql(Sinotify::CREATE | Sinotify::MODIFY)
+
+    # should not be able to create a notifier using a bogus event type (eg. 'blah')
+    lambda{Sinotify::Notifier.new('/tmp', :recurse => false, :etypes => [:blah])}.should raise_error
+    lambda{Sinotify::Notifier.new('/tmp', :recurse => false, :etypes => [:create, :blah])}.should raise_error
+  end
+
+  it "should properly create Event from PrimEvent" do
+    # mimic delete of a directory -- change :delete_self into :delete
+    prim_event = MockPrimEvent.new
+    prim_event.etypes = [:delete_self]
+    watch = Sinotify::Watch.new(:is_dir => true, :path => '/tmp')
+    event = Sinotify::Event.from_prim_event_and_watch(prim_event, watch)
+    event.etypes.should be_include(:delete)
+    event.etypes.should_not be_include(:delete_self)
+
+    # :close should get added if event is :close_nowrite or :close_write
+    prim_event = MockPrimEvent.new
+    prim_event.etypes = [:close_nowrite]
+    event = Sinotify::Event.from_prim_event_and_watch(prim_event, watch)
+    event.etypes.should be_include(:close)
+    prim_event = MockPrimEvent.new
+    prim_event.etypes = [:close_write]
+    event = Sinotify::Event.from_prim_event_and_watch(prim_event, watch)
+    event.etypes.should be_include(:close)
+  end
+
+  it "should add watches for all child directories if recursive" do
+
+    reset_test_dir!
+
+    # make a watch, recurse false. There should only be one watch
+    notifier = Sinotify::Notifier.new(@test_root_dir, :recurse => false).watch!
+
+    tiny_pause!
+    notifier.all_directories_being_watched.should be_eql([@test_root_dir])
+
+    # make a watch, recurse TRUE. There should only be 27 watches (a-z, and @test_root_dir)
+    notifier = Sinotify::Notifier.new(@test_root_dir, 
+                                      :etypes => [:all_events],
+                                      :recurse => true).watch!
+    # notifier.spy!(:logger => Logger.new('/tmp/spy.log'))
+
+    pause!
+    notifier.all_directories_being_watched.size.should be_eql(27)
+
+    # check a single announcement on a file in a subdir
+    events = []
+    test_fn = File.join(@test_root_dir, 'a', 'hi')
+    notifier.on_event { |event| events << event }
+    FileUtils.touch test_fn
+    pause!
+    #puts events.map{|e|e.to_s}.join("\n")
+    events.detect{|e| e.path.eql?(test_fn) && e.etypes.include?(:create) }.should_not be_nil
+    events.detect{|e| e.path.eql?(test_fn) && e.etypes.include?(:open) }.should_not be_nil
+    events.detect{|e| e.path.eql?(test_fn) && e.etypes.include?(:close_write) }.should_not be_nil
+    events.detect{|e| e.path.eql?(test_fn) && e.etypes.include?(:close) }.should_not be_nil
+
+    events = []
+    File.open(test_fn, 'a'){|f| f << 'ho'}
+    pause!
+    events.detect{|e| e.path.eql?(test_fn) && e.etypes.include?(:open) }.should_not be_nil
+    events.detect{|e| e.path.eql?(test_fn) && e.etypes.include?(:modify) }.should_not be_nil
+    events.detect{|e| e.path.eql?(test_fn) && e.etypes.include?(:close_write) }.should_not be_nil
+    events.detect{|e| e.path.eql?(test_fn) && e.etypes.include?(:close) }.should_not be_nil
+
+    # quickly create and delete the file
+    events = []
+    FileUtils.rm test_fn
+    tiny_pause!
+    FileUtils.touch test_fn
+    pause!
+    events.detect{|e| e.path.eql?(test_fn) && e.etypes.include?(:delete) }.should_not be_nil
+    events.detect{|e| e.path.eql?(test_fn) && e.etypes.include?(:create) }.should_not be_nil
+  end
+
+  it "should add a watch when a new subdirectory is created" do
+    # setup
+    reset_test_dir! # creates 27 directories, the root dir and 'a'...'z'
+    subdir_a = File.join(@test_root_dir, 'a')
+    events = []
+    notifier = Sinotify::Notifier.new(@test_root_dir, :recurse => true).watch!
+    #notifier.spy!(:logger => spylog = Logger.new(STDOUT))
+    notifier.on_event { |event| events << event }
+
+    # one watch for the root and the 26 subdirs 'a'..'z'
+    pause!
+    notifier.all_directories_being_watched.size.should be_eql(27) 
+
+    # create a new subdir
+    subdir_abc = File.join(@test_root_dir, 'a', 'abc')
+    FileUtils.mkdir subdir_abc
+    pause! # takes a moment to sink in because the watch is added in a bg thread
+    notifier.all_directories_being_watched.size.should be_eql(28) 
+    pause!
+
+    # create a file in the new subdir, it should send and event
+    file_in_subdir_abc = File.join(subdir_abc, 'new_file')
+    events_before = events.size
+    FileUtils.touch file_in_subdir_abc
+    pause!
+    events.size.should be_eql(events_before + 1)
+  end
+
+  it "should delete watches for on subdirectories when a parent directory is deleted" do
+
+    # Setup (create the usual test dir and 26 subdirs, and an additional sub-subdir, and a file
+    reset_test_dir! # creates the root dir and 'a'...'z'
+    subdir_a = File.join(@test_root_dir, 'a')
+    FileUtils.mkdir File.join(@test_root_dir, 'a', 'def')
+    test_fn = File.join(subdir_a, 'hi')
+    FileUtils.touch test_fn
+
+    # Setup: create the notifier
+    events = []
+    notifier = Sinotify::Notifier.new(@test_root_dir, :recurse => true).watch!
+    #notifier.spy!(:logger => Logger.new('/tmp/spy.log'))
+    notifier.on_event { |event|  events << event }
+
+    # first assert: all directories should have a watch
+    pause!
+    notifier.all_directories_being_watched.size.should be_eql(28) # all the directories should have watches
+
+
+    # Should get delete events for the subdir_a and its file 'hi' when removing subdir_a.
+    # There should be 26 watches left (after removing watches for subdir_a and its sub-subdir)
+    FileUtils.rm_rf subdir_a
+    pause!
+    events.detect{|e| e.path.eql?(subdir_a) && e.directory? && e.etypes.include?(:delete) }.should_not be_nil
+    events.detect{|e| e.path.eql?(test_fn) && !e.directory? && e.etypes.include?(:delete) }.should_not be_nil
+    notifier.all_directories_being_watched.size.should be_eql(26)
+  end
+
+  it "should exit and nil out watch_thread when closed" do
+    # really need this?
+  end
+
+  it "should close children when closed if recursive" do
+    # Setup (create the usual test dir and 26 subdirs, and an additional sub-subdir, and a file
+    reset_test_dir! # creates the root dir and 'a'...'z'
+    FileUtils.mkdir File.join(@test_root_dir, 'a', 'def')
+
+    # Setup: create the notifier
+    events = []
+    notifier = Sinotify::Notifier.new(@test_root_dir, :recurse => true).watch!
+    #notifier.spy!(:logger => Logger.new('/tmp/spy.log'))
+    notifier.on_event { |event|  events << event }
+
+    # first assert: all directories should have a watch
+    pause!
+    notifier.all_directories_being_watched.size.should be_eql(28) # all the directories should have watches
+
+    notifier.close!
+    notifier.all_directories_being_watched.size.should be_eql(0) # all watches should have been deleted
+  end
+
+  it "pound it" do
+    # Setup (create the usual test dir and 26 subdirs, and an additional sub-subdir, and a file
+    reset_test_dir! # creates the root dir and 'a'...'z'
+
+    a_z = ('a'..'z').collect{|x|x}
+
+    # Setup: create the notifier
+    notifier = Sinotify::Notifier.new(@test_root_dir, 
+                                      :announcements_sleep_time => 0.01,
+                                      :announcement_throttle => 10000,
+                                      :etypes => [:create, :modify, :delete, :close],
+                                      :recurse => true).watch!
+    #notifier.spy!(:logger => Logger.new('/tmp/spy.log'))
+    creates = deletes = modifies = closes = 0
+    notifier.on_event do |event|  
+      creates += 1 if event.etypes.include?(:create) 
+      deletes += 1 if event.etypes.include?(:delete) 
+      modifies += 1 if event.etypes.include?(:modify) 
+      closes += 1 if event.etypes.include?(:close) 
+    end
+
+    # Create, append to, and then delete a bunch of random files
+    tiny_pause!
+    total_iterations = 1000
+    total_iterations.times do 
+      sub_dir = File.join(@test_root_dir, a_z[rand(a_z.size)])
+      test_fn = File.join(sub_dir, "zzz#{rand(10000)}")
+      FileUtils.touch test_fn
+      File.open(test_fn, 'a'){|f| f << rand(1000).to_s }
+      FileUtils.rm test_fn
+    end
+    puts "created and modified and deleted #{total_iterations} files in sub directories of #{@test_root_dir}"
+
+    start_wait = Time.now
+
+    # wait up to 15 seconds for all the create events to come through
+    waits = 0
+    puts "Waiting for events, will wait for up to 30 sec"
+    while(creates < total_iterations) do
+      sleep 1
+      waits += 1
+      break if waits > 30
+      #raise "Tired of waiting for create events to reach #{total_iterations}, it is only at #{creates}" if waits > 30
+    end
+
+    puts "It took #{Time.now - start_wait} seconds for all the create/modify/delete/close events to come through"
+
+    # give it a tiny bit longer to let any remaining modify/delete/close stragglers to come through
+    5.times{tiny_pause!}
+
+    puts "Ceates detected: #{creates}"
+    puts "Deletes: #{deletes}"
+    puts "Modifies: #{modifies}"
+    puts "Closes: #{closes}"
+
+    creates.should be_eql(total_iterations) 
+    deletes.should be_eql(total_iterations) 
+    modifies.should be_eql(total_iterations) 
+    closes.should be_eql(2 * total_iterations) # should get a close both after the create and the modify
+
+  end
+
+end
+
+# EOF