swerling-sinotify 0.0.1 → 0.0.2

data/.gitignore

@@ -1,5 +1,8 @@
 pkg/
+doc/
+rdoc/
 ext/Makefile
 ext/mkmf.log
 ext/*.o
 ext/*.so
+*.swp

data/README.rdoc

@@ -1,6 +1,8 @@
-sinotify
-    by Steven Swerling
-    http://tab-a.slot-z.net
+sinotify 
+
+by {Steven Swerling}[http://tab-a.slot-z.net]
+
+{rdoc}[http://tab-a.slot-z.net] | {github}[http://www.github.com/swerling/sinotify]
 
 == DESCRIPTION:
 

data/README.txt

@@ -1,6 +1,8 @@
-sinotify
-    by Steven Swerling
-    http://tab-a.slot-z.net
+sinotify 
+
+by {Steven Swerling}[http://tab-a.slot-z.net]
+
+{rdoc}[http://tab-a.slot-z.net] | {github}[http://www.github.com/swerling/sinotify]
 
 == DESCRIPTION:
 
@@ -63,10 +65,10 @@ Try this:
   require 'sinotify'
   notifier = Sinotify::Notifier.new('/tmp/sinotify_test', :recurse => true, :etypes => [:create, :modify, :delete])
   notifier.spy!(:logger => Logger.new('/tmp/inotify_spy.log')) # optional event spy
-  notifier.when_announcing(Sinotify::Event) do |sinotify_event|
+  notifier.on_event do |sinotify_event|
     puts "Event happened at #{sinotify_event.timestamp} on #{sinotify_event.path}, etypes => #{sinotify_event.etypes.inspect}"
   end
-  notifier.when_announcing(Sinotify::Event) do |sinotify_event|
+  notifier.on_event do |sinotify_event|
     puts "    --> demonstrate that multiple subscribers can be setup: #{sinotify_event.etypes.inspect}"
   end
   notifier.watch! # don't forget to start the watch

data/Rakefile

@@ -30,21 +30,43 @@ PROJ.spec.opts << '--color'
 PROJ.rdoc.opts = ["--inline-source"]
 PROJ.rdoc.exclude = ["^tasks/setup\.rb$", "\.[ch]$"]
 
+
+
+
+
+require 'fileutils'
+def this_dir; File.join(File.dirname(__FILE__)); end
+def doc_dir; File.join(this_dir, 'rdoc'); end
+def ext_dir; File.join(this_dir, 'ext'); end
+def tab_a_doc_dir; File.join(this_dir, '../tab-a/public/sinotify/rdoc'); end
+
 task :default => 'spec:run'
 task :myclobber => [:clobber] do
-  sh "rm -rf #{File.join(File.dirname(__FILE__), 'pkg')}"
-  sh "rm -rf #{File.join(File.dirname(__FILE__), 'doc')}"
-  sh "rm -rf #{File.join(File.dirname(__FILE__), 'ext/*.log')}"
-  sh "rm -rf #{File.join(File.dirname(__FILE__), 'ext/*.o')}"
-  sh "rm -rf #{File.join(File.dirname(__FILE__), 'ext/*.so')}"
-  sh "rm -rf #{File.join(File.dirname(__FILE__), 'ext/Makefile')}"
+  mydir = File.join(File.dirname(__FILE__))
+  sh "rm -rf #{File.join(mydir, 'pkg')}"
+  sh "rm -rf #{File.join(mydir, 'doc')}"
+  sh "rm -rf #{File.join(mydir, 'rdoc')}"
+  sh "rm -rf #{File.join(mydir, 'ext/*.log')}"
+  sh "rm -rf #{File.join(mydir, 'ext/*.o')}"
+  sh "rm -rf #{File.join(mydir, 'ext/*.so')}"
+  sh "rm -rf #{File.join(mydir, 'ext/Makefile')}"
+  sh "rm -rf #{File.join(mydir, 'ext/Makefile')}"
 end
 task :mypackage => [:myclobber] do
-  sh "rm -rf #{File.join(File.dirname(__FILE__), 'pkg')}"
-  sh "rm -rf #{File.join(File.dirname(__FILE__), 'doc')}"
-  sh "rm -rf #{File.join(File.dirname(__FILE__), 'ext/*.log')}"
-  sh "rm -rf #{File.join(File.dirname(__FILE__), 'ext/*.o')}"
-  sh "rm -rf #{File.join(File.dirname(__FILE__), 'ext/*.so')}"
   Rake::Task['gem:package'].invoke
 end
-
+task :mydoc => [:myclobber] do
+  FileUtils.rm_f doc_dir()
+  sh "cd #{this_dir()} && rdoc -o rdoc --inline-source --format=html -T hanna README.rdoc lib/**/*.rb" 
+end
+task :taba => [:mydoc] do
+  this_dir = File.join(File.dirname(__FILE__))
+  FileUtils.rm_rf tab_a_doc_dir
+  FileUtils.cp_r doc_dir, tab_a_doc_dir
+end
+task :mygemspec => [:myclobber] do
+  Rake::Task['gem:spec'].invoke
+end
+task :mybuild => [:myclobber] do
+  sh "cd #{ext_dir} && ruby extconf.rb && make"
+end

data/TODO

@@ -0,0 +1,12 @@
+1. Refactor Notifier and Event so that other operating systems can be used for prim events.
+
+   Currently there are couplings between Event and PrimEvent that assume linux (easy to remove),
+   and couplings between Notifier and PrimEvent that assume linux (harder to remove, will need
+   an adapter class)
+
+2. Batch collate events
+
+   Currently if you remove or add a directory with lots of files, events are sent out for
+   every single file. Would be nice option if a single event listing all the changes went
+   out (say, a single event that sponges up all events for 150 milliseconds, then sends them
+   off as an array)

data/lib/sinotify/notifier.rb

@@ -32,7 +32,8 @@ module Sinotify
     #    :etypes => 
     #      which inotify file system event types to listen for (eg :create, :delete, etc)
     #      See docs for Sinotify::Event for list of event types.
-    #      default is :all_types
+    #      default is [:create, :modify, :delete]
+    #      Use :all_events to trace everything (although this may be more than you bargained for).
     #
     #    :logger => 
     #      Where to log errors to. Default is Logger.new(STDOUT).
@@ -60,7 +61,7 @@ module Sinotify
       # how many directories at a time to register. 
       self.recurse_throttle = opts[:recurse_throttle] || 10 
 
-      self.etypes = Array(opts[:etypes] || :all_events)
+      self.etypes = Array( opts[:etypes] || [:create, :modify, :delete] )
       validate_etypes!
 
       self.prim_notifier = Sinotify::PrimNotifier.new
@@ -70,7 +71,7 @@ module Sinotify
       sleep_time = opts[:announcements_sleep_time] || 0.05 
       announcement_throttle = opts[:announcement_throttle] || 50 
       self.queue_announcements!(:sleep_time => sleep_time, 
-                                :logger => opts[:logger], 
+                                :logger => @logger,
                                 :announcements_per_cycle => announcement_throttle)
 
       self.closed = false
@@ -81,6 +82,24 @@ module Sinotify
       @spy_logger_level = nil
       @watch_thread = nil
     end
+
+    # Sugar. 
+    #
+    # Equivalent of calling cosell's
+    #
+    #    self.when_announcing(Sinotify::Event) do |event| 
+    #      do_something_with_event(event) 
+    #    end
+    #
+    # becomes
+    #
+    #    self.on_event { |event| do_something_with_event(event) }
+    #
+    # Since this class only announces one kind of event, it made sense to 
+    # provide a more terse version of that statement.
+    def on_event &block
+      self.when_announcing(Sinotify::Event, &block)
+    end
     
     # whether this watch is on a directory
     def on_directory?
@@ -108,10 +127,12 @@ module Sinotify
     # Options:
     #    :logger => The log to log to. Default is a logger on STDOUT
     #    :level => The log level to log with. Default is :info
+    #    :spy_on_prim_events => Spy on PrimEvents (raw inotify events) too
     #
     def spy!(opts = {})
-      @spy_logger = opts[:logger] || Logger.new(STDOUT)
-      @spy_logger_level = opts[:level] || :info
+      self.spy_on_prim_events = opts[:spy_on_prim_events].eql?(true)
+      self.spy_logger = opts[:logger] || Logger.new(STDOUT)
+      self.spy_logger_level = opts[:level] || :info
       opts[:on] = Sinotify::Event
       opts[:preface_with] = "Sinotify::Notifier Event Spy"
       super(opts)
@@ -141,6 +162,8 @@ module Sinotify
 
       #:stopdoc: 
  
+      attr_accessor :spy_on_prim_events, :spy_logger, :spy_logger_level
+
       def validate_etypes!
         bad = self.etypes.detect{|etype| PrimEvent.mask_from_etype(etype).nil? }
         raise "Unrecognized etype '#{bad}'. Please see valid list in docs for Sinotify::Event" if bad
@@ -229,13 +252,6 @@ module Sinotify
         self.logger.send(level, msg) if self.logger
       end
 
-      def spy_on_event(prim_event)
-        if @spy_logger
-          msg = "Sinotify::Notifier Prim Event Spy: #{prim_event.inspect}"
-          @spy_logger.send(@spy_logger_level, msg)
-        end
-      end
-
       # Listen for linux inotify events, and as they come in
       #   1. adapt them into Sinotify::Event objects 
       #   2. 'announce' them using Cosell. 
@@ -255,9 +271,9 @@ module Sinotify
             self.prim_notifier.each_event do |prim_event|
               watch = self.watches[prim_event.watch_descriptor.to_s]
               if event_is_noise?(prim_event, watch)
-                @spy_logger.debug("Sinotify::Notifier Spy: Skipping noise[#{prim_event.inspect}]") if @spy_logger
+                self.spy_logger.debug("Sinotify::Notifier Spy: Skipping noise[#{prim_event.inspect}]") if self.spy_on_prim_events
               else
-                spy_on_event(prim_event)
+                spy_on_prim_event(prim_event)
                 if watch.nil?
                   self.log "Could not determine watch from descriptor #{prim_event.watch_descriptor}, something is wrong. Event: #{prim_event.inspect}", :warn
                 else
@@ -294,6 +310,13 @@ module Sinotify
         @raw_mask
       end
 
+      def spy_on_prim_event(prim_event)
+        if self.spy_on_prim_events
+          msg = "Sinotify::Notifier Prim Event Spy: #{prim_event.inspect}"
+          self.spy_logger.send(@spy_logger_level, msg)
+        end
+      end
+
       # ruby gives warnings in verbose mode if you use attr_accessor to set these next few: 
       def prim_notifier; @prim_notifier; end
       def prim_notifier= x; @prim_notifier = x; end

data/lib/sinotify/prim_event.rb

@@ -60,10 +60,6 @@ module Sinotify
     @@etype_to_mask_map = {}
     @@mask_to_etype_map.each{|k,v| @@etype_to_mask_map[v] = k}
 
-#    def self.etype_from_mask(mask)
-#      @@mask_to_etype_map[mask]
-#    end
-
     def self.etype_from_mask(mask)
       @@mask_to_etype_map[mask]
     end

data/lib/sinotify_info.rb

@@ -1,6 +1,6 @@
 module Sinotify
 
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 
   # :stopdoc:
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR

data/sinotify.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{sinotify}
-  s.version = "0.0.1"
+  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-07-19}
+  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). 
@@ -53,12 +53,13 @@ Selected quotes from the README for inotify:
   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", "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.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.3}
+  s.rubygems_version = %q{1.3.2}
   s.summary = %q{ALPHA Alert -- just uploaded initial release}
 
   if s.respond_to? :specification_version then
@@ -67,13 +68,13 @@ Selected quotes from the README for inotify:
 
     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.4.0"])
+      s.add_development_dependency(%q<bones>, [">= 2.5.1"])
     else
       s.add_dependency(%q<cosell>, [">= 0"])
-      s.add_dependency(%q<bones>, [">= 2.4.0"])
+      s.add_dependency(%q<bones>, [">= 2.5.1"])
     end
   else
     s.add_dependency(%q<cosell>, [">= 0"])
-    s.add_dependency(%q<bones>, [">= 2.4.0"])
+    s.add_dependency(%q<bones>, [">= 2.5.1"])
   end
 end

data/spec/sinotify_spec.rb

@@ -15,11 +15,17 @@ end
 describe Sinotify do
 
   # A lot of Sinotify work occurs in background threads (eg. adding watches, adding subdirectories),
-  # so the tests may insert a tiny pause to allow the bg threads to do their thing before making
+  # so the tests may insert a tiny pauses to allow the bg threads to do their thing before making
   # any assertions. 
-  def tiny_pause!; sleep 0.05; end
-  def pause!; sleep 0.5; end
-  def big_pause!; sleep 1.5; end
+  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\//
@@ -74,7 +80,9 @@ describe Sinotify do
     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, :recurse => true).watch!
+    notifier = Sinotify::Notifier.new(@test_root_dir, 
+                                      :etypes => [:all_events],
+                                      :recurse => true).watch!
     # notifier.spy!(:logger => Logger.new('/tmp/spy.log'))
 
     pause!
@@ -83,7 +91,7 @@ describe Sinotify do
     # check a single announcement on a file in a subdir
     events = []
     test_fn = File.join(@test_root_dir, 'a', 'hi')
-    notifier.when_announcing(Sinotify::Event) { |event|  events << event }
+    notifier.on_event { |event| events << event }
     FileUtils.touch test_fn
     pause!
     #puts events.map{|e|e.to_s}.join("\n")
@@ -116,21 +124,29 @@ describe Sinotify do
     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('/tmp/spy.log'))
-    notifier.when_announcing(Sinotify::Event) { |event|  events << event }
+    #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
-    FileUtils.mkdir File.join(@test_root_dir, 'a', 'abc')
-    big_pause! # takes a moment to sink in because the watch is added in a bg thread
+    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 subdirectires when a parent directory is deleted" do
+  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'
@@ -143,7 +159,7 @@ describe Sinotify do
     events = []
     notifier = Sinotify::Notifier.new(@test_root_dir, :recurse => true).watch!
     #notifier.spy!(:logger => Logger.new('/tmp/spy.log'))
-    notifier.when_announcing(Sinotify::Event) { |event|  events << event }
+    notifier.on_event { |event|  events << event }
 
     # first assert: all directories should have a watch
     pause!
@@ -172,7 +188,7 @@ describe Sinotify do
     events = []
     notifier = Sinotify::Notifier.new(@test_root_dir, :recurse => true).watch!
     #notifier.spy!(:logger => Logger.new('/tmp/spy.log'))
-    notifier.when_announcing(Sinotify::Event) { |event|  events << event }
+    notifier.on_event { |event|  events << event }
 
     # first assert: all directories should have a watch
     pause!
@@ -196,7 +212,7 @@ describe Sinotify do
                                       :recurse => true).watch!
     #notifier.spy!(:logger => Logger.new('/tmp/spy.log'))
     creates = deletes = modifies = closes = 0
-    notifier.when_announcing(Sinotify::Event) do |event|  
+    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) 
@@ -226,9 +242,11 @@ describe Sinotify do
       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"
 
-    pause!; pause!; pause! # give it a tiny bit longer to let any remaining modify/delete/close stragglers 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}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: swerling-sinotify
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Steven Swerling
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-19 00:00:00 -07:00
+date: 2009-08-09 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -30,7 +30,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 2.4.0
+        version: 2.5.1
     version: 
 description: "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.')"
 email: sswerling@yahoo.com
@@ -47,6 +47,7 @@ files:
 - README.rdoc
 - README.txt
 - Rakefile
+- TODO
 - examples/watcher.rb
 - ext/extconf.rb
 - ext/src/inotify-syscalls.h
@@ -62,8 +63,9 @@ files:
 - spec/prim_notify_spec.rb
 - spec/sinotify_spec.rb
 - spec/spec_helper.rb
-has_rdoc: false
+has_rdoc: true
 homepage: http://tab-a.slot-z.net
+licenses: 
 post_install_message: 
 rdoc_options: 
 - --inline-source
@@ -87,7 +89,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: sinotify
-rubygems_version: 1.2.0
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
 summary: ALPHA Alert -- just uploaded initial release