rb-fchange 0.0.2

data/README.md

@@ -0,0 +1,31 @@
+# rb-fchange
+
+Code not ready. It's just proof of concept
+This is a simple wrapper over the Windows Kernel functions for monitoring the specified directory or subtree.
+
+Example
+
+```ruby
+  require 'rb-fchange'
+  
+  notifier = FChange::Notifier.new
+  notifier.watch("test", :all_events, :recursive) do |event|
+    p Time.now.utc
+  end
+  
+  Signal.trap('INT') do
+    p "Bye bye...",
+    notifier.stop
+    abort("\n")
+  end
+  
+  notifier.run
+```
+
+## TODO
+
+ - add latency setting with 0.5 default
+ - default flag for events :all_events
+ - rework interface (should more look like rb-fsevent)
+ - add specs (can use specs from rb-fsevent)
+ - publish on rubygems

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/lib/rb-fchange.rb

@@ -0,0 +1,14 @@
+require "rb-fchange/native"
+require "rb-fchange/native/flags"
+require "rb-fchange/notifier"
+require "rb-fchange/watcher"
+require "rb-fchange/event"
+
+# The root module of the library, which is laid out as so:
+#
+# * {Notifier} -- The main class, where the notifications are set up
+# * {Watcher} -- A watcher for a single file or directory
+# * {Event} -- An filesystem event notification
+module FChange
+
+end

data/lib/rb-fchange/event.rb

@@ -0,0 +1,29 @@
+module FChange
+  # An event caused by a change on the filesystem.
+  # Each {Watcher} can fire many events,
+  # which are passed to that watcher's callback.
+  class Event
+    # The {Watcher} that fired this event.
+    #
+    # @return [Watcher]
+    attr_reader :watcher
+    
+    # Creates an event from a string of binary data.
+    # Differs from {Event.consume} in that it doesn't modify the string.
+    #
+    # @private
+    # @param watcher [Watcher] The {Watcher} that fired the event
+    def initialize(watcher)
+      @watcher = watcher
+    end
+
+    # Calls the callback of the watcher that fired this event,
+    # passing in the event itself.
+    #
+    # @private
+    def callback!
+      @watcher.callback!(self)
+    end
+
+  end
+end

data/lib/rb-fchange/native.rb

@@ -0,0 +1,70 @@
+require 'win32/api'
+
+module FChange
+  # This module contains the low-level foreign-function.
+  # It's an implementation detail, and not meant for users to deal with.
+  #
+  # @private
+  module Native
+
+    #
+    INFINITE = 0xFFFFFFFF
+
+    #
+    WAIT_OBJECT_0 = 0x00000000
+      
+    # HANDLE FindFirstChangeNotification(
+    #  LPCTSTR lpPathName,    // directory name
+    #  BOOL bWatchSubtree,    // monitoring option
+    #  DWORD dwNotifyFilter   // filter conditions
+    #);
+    @_k32FindFirstChangeNotification = 
+      Win32::API.new('FindFirstChangeNotification', ['P', 'I', 'L'], 'L')
+
+    # @return handle
+    def k32FindFirstChangeNotification(path, recursive, flag)
+        @_k32FindFirstChangeNotification.call(path, recursive ? 1 : 0, flag)
+    end
+    
+    module_function "k32FindFirstChangeNotification"
+    
+    # BOOL FindNextChangeNotification(
+    #  HANDLE hChangeHandle   // handle to change notification
+    # );
+    @_k32FindNextChangeNotification = 
+      Win32::API.new('FindNextChangeNotification', ['L'], 'I')
+    
+    def k32FindNextChangeNotification(handle)
+        @_k32FindNextChangeNotification.call(handle)
+    end
+    
+    module_function "k32FindNextChangeNotification"
+
+    # DWORD WaitForMultipleObjects(
+    #   DWORD nCount,             // number of handles in array
+    #   CONST HANDLE *lpHandles,  // object-handle array
+    #   BOOL bWaitAll,            // wait option
+    #   DWORD dwMilliseconds      // time-out interval
+    # );
+    @_k32WaitForMultipleObjects = 
+      Win32::API.new('WaitForMultipleObjects', ['L', 'P', 'I', 'L'], 'L')
+    
+    def k32WaitForMultipleObjects(count, handles, wait_all, time)
+        @_k32WaitForMultipleObjects.call(count, handles, wait_all, time)
+    end
+    
+    module_function "k32WaitForMultipleObjects"
+
+    # BOOL FindCloseChangeNotification(
+    #   HANDLE hChangeHandle
+    # );
+    @_k32FindCloseChangeNotification = 
+      Win32::API.new('FindCloseChangeNotification', ['L'], 'I')
+
+    def k32FindCloseChangeNotification(handle)
+        @_k32FindCloseChangeNotification.call(handle)
+    end
+    
+    module_function "k32FindCloseChangeNotification"
+  end
+end

data/lib/rb-fchange/native/flags.rb

@@ -0,0 +1,83 @@
+module FChange
+  module Native
+    # A module containing all the flags to be passed to {Notifier#watch}.
+    # @see http://msdn.microsoft.com/en-us/library/aa364417(v=VS.85).aspx 
+    # 
+    # @private
+    module Flags
+
+      # Any file name change in the watched directory or subtree causes a change
+      # notification wait operation to return. Changes include renaming, 
+      # creating, or deleting a file name.
+      FILE_NOTIFY_CHANGE_FILE_NAME   = 0x00000001
+
+      # Any directory-name change in the watched directory or subtree causes a 
+      # change notification wait operation to return. Changes include creating 
+      # or deleting a directory.
+      FILE_NOTIFY_CHANGE_DIR_NAME    = 0x00000002
+
+      # Any attribute change in the watched directory or subtree causes a change
+      # notification wait operation to return.
+      FILE_NOTIFY_CHANGE_ATTRIBUTES  = 0x00000004
+
+      # Any file-size change in the watched directory or subtree causes a change
+      # notification wait operation to return. The operating system detects a 
+      # change in file size only when the file is written to the disk. 
+      # For operating systems that use extensive caching, detection occurs only 
+      # when the cache is sufficiently flushed.
+      FILE_NOTIFY_CHANGE_SIZE        = 0x00000008
+
+      # Any change to the last write-time of files in the watched directory or 
+      # subtree causes a change notification wait operation to return.
+      # The operating system detects a change to the last write-time only when 
+      # the file is written to the disk. For operating systems that use 
+      # extensive caching, detection occurs only when the cache is sufficiently 
+      # flushed
+      FILE_NOTIFY_CHANGE_LAST_WRITE  = 0x00000010
+
+      # Any change to the last access time of files in the watched directory or 
+      # subtree causes a change notification wait operation to return.
+      FILE_NOTIFY_CHANGE_LAST_ACCESS = 0x00000020
+
+      # Any change to the creation time of files in the watched directory or 
+      # subtree causes a change notification wait operation to return.
+      FILE_NOTIFY_CHANGE_CREATION    = 0x00000040
+
+      # Any security-descriptor change in the watched directory or subtree 
+      # causes a change notification wait operation to return.
+      FILE_NOTIFY_CHANGE_SECURITY    = 0x00000100
+
+      FILE_NOTIFY_CHANGE_ALL_EVENTS = (
+        FILE_NOTIFY_CHANGE_ATTRIBUTES |
+        FILE_NOTIFY_CHANGE_CREATION |
+        FILE_NOTIFY_CHANGE_DIR_NAME |
+        FILE_NOTIFY_CHANGE_FILE_NAME |
+        FILE_NOTIFY_CHANGE_LAST_ACCESS |
+        FILE_NOTIFY_CHANGE_LAST_WRITE |
+        FILE_NOTIFY_CHANGE_SECURITY |
+        FILE_NOTIFY_CHANGE_SIZE
+      )
+
+      # Converts a list of flags to the bitmask that the C API expects.
+      #
+      # @param flags [Array<Symbol>]
+      # @return [Fixnum]
+      def self.to_mask(flags)
+        flags.map {|flag| const_get("FILE_NOTIFY_CHANGE_#{flag.to_s.upcase}")}.
+          inject(0) {|mask, flag| mask | flag}
+      end
+
+      # Converts a bitmask from the C API into a list of flags.
+      #
+      # @param mask [Fixnum]
+      # @return [Array<Symbol>]
+      def self.from_mask(mask)
+        constants.map {|c| c.to_s}.select do |c|
+          next false unless c =~ /^FILE_NOTIFY_CHANGE_/
+          const_get(c) & mask != 0
+        end.map {|c| c.sub("FILE_NOTIFY_CHANGE_", "").downcase.to_sym} - [:all_events]
+      end
+
+    end
+  end
+end

data/lib/rb-fchange/notifier.rb

@@ -0,0 +1,139 @@
+module FChange
+  # Notifier wraps a single instance of FChange.
+  # It's possible to have more than one instance,
+  # but usually unnecessary.
+  #
+  # @example
+  #   # Create the notifier
+  #   notifier = FChange::Notifier.new
+  #
+  #   # Run this callback whenever the file path/to/foo.txt is read
+  #   notifier.watch("path/to/foo/", :all_events) do
+  #     puts "foo was accessed!"
+  #   end
+  #
+  #   # Nothing happens until you run the notifier!
+  #   notifier.run
+  class Notifier
+    # A hash from {Watcher} ids to the instances themselves.
+    #
+    # @private
+    # @return [{Fixnum => Watcher}]
+    attr_reader :watchers
+    
+    attr_reader :dwChangeHandles
+    attr_reader :lp_dwChangeHandles
+
+    # Creates a new {Notifier}.
+    #
+    # @return [Notifier] 
+    def initialize
+      @watchers = {}
+      @dwChangeHandles = []
+      @lp_dwChangeHandles = 0
+    end
+
+    # Adds a new {Watcher} to the queue.
+    def add_watcher(watcher)
+
+      @watchers[watcher.id] = watcher
+
+      @dwChangeHandles.push watcher.id
+
+      # Pack event handles into newly created storage area 
+      # to be used for Win32 call
+      @lp_dwChangeHandles = dwChangeHandles.pack("L" * dwChangeHandles.count)
+
+    end
+
+    # Watches a file or directory for changes,
+    # calling the callback when there are.
+    # This is only activated once \{#process} or \{#run} is called.
+    #
+    # **Note that by default, this does not recursively watch subdirectories
+    # of the watched directory**.
+    # To do so, use the `:recursive` flag.
+    #
+    # `:recursive`
+    # : Recursively watch any subdirectories that are created.
+    #
+    # @param path [String] The path to the file or directory
+    # @param flags [Array<Symbol>] Which events to watch for
+    # @yield [event] A block that will be called
+    #   whenever one of the specified events occur
+    # @yieldparam event [Event] The Event object containing information
+    #   about the event that occured
+    # @return [Watcher] A Watcher set up to watch this path for these events
+    # @raise [SystemCallError] if the file or directory can't be watched,
+    #   e.g. if the file isn't found, read access is denied,
+    #   or the flags don't contain any events
+    def watch(path, *flags, &callback)
+      recursive = flags.include?(:recursive)
+      flags.include?(:recursive)
+      #:latency = 0.5
+      flags = flags - [:recursive]
+      @flags = flags.freeze
+      Watcher.new(self, path, recursive, *flags, &callback)      
+    end
+
+    # Starts the notifier watching for filesystem events.
+    # Blocks until \{#stop} is called.
+    #
+    # @see #process
+    def run
+      @stop = false
+      process until @stop
+    end
+
+    # Stop watching for filesystem events.
+    # That is, if we're in a \{#run} loop,
+    # exit out as soon as we finish handling the events.
+    def stop
+      @stop = true
+    end
+
+    # Blocks until there are one or more filesystem events
+    # that this notifier has watchers registered for.
+    # Once there are events, the appropriate callbacks are called
+    # and this function returns.
+    #
+    # @see #run
+    def process
+      read_events.each {|event| event.callback!}
+    end
+
+    # Blocks until there are one or more filesystem events
+    # that this notifier has watchers registered for.
+    # Once there are events, returns their {Event} objects.
+    #
+    # @private
+    def read_events
+
+      # can return WAIT_TIMEOUT  = 0x00000102
+      dwWaitStatus = Native.k32WaitForMultipleObjects(@dwChangeHandles.count, 
+        @lp_dwChangeHandles, 0, 500)
+
+      events = []
+
+      # this call blocks all threads completely.
+      @dwChangeHandles.each_index do |index|
+        if dwWaitStatus == Native::WAIT_OBJECT_0 + index
+
+          ev = Event.new(@watchers[@dwChangeHandles[index]])
+          events << ev
+        
+          r = Native.k32FindNextChangeNotification(@dwChangeHandles[index]) 
+          if r == 0 
+              raise SystemCallError.new("Failed to watch", r) 
+          end
+        end
+      end
+      events
+    end
+
+    def close
+      
+    end
+
+  end
+end

data/lib/rb-fchange/watcher.rb

@@ -0,0 +1,80 @@
+module FChange
+  # Watchers monitor a single path for changes,
+  # specified by {FChange::Notifier#watch event flags}.
+  # A watcher is usually created via \{Notifier#watch}.
+  #
+  # One {Notifier} may have many {Watcher}s.
+  # The Notifier actually takes care of the checking for events,
+  # via \{Notifier#run #run} or \{Notifier#process #process}.
+  # The main purpose of having Watcher objects
+  # is to be able to disable them using \{#close}.
+  class Watcher
+    # The {Notifier} that this Watcher belongs to.
+    #
+    # @return [Notifier]
+    attr_reader :notifier
+
+    # The path that this Watcher is watching.
+    #
+    # @return [String]
+    attr_reader :path
+
+    # The {FChange::Notifier#watch flags}
+    # specifying the events that this Watcher is watching for,
+    # and potentially some options as well.
+    #
+    # @return [Array<Symbol>]
+    attr_reader :flags
+    
+    # The id for this Watcher.
+    # Used to retrieve this Watcher from {Notifier#watchers}.
+    #
+    # @private
+    # @return [Fixnum]
+    attr_reader :id
+
+    #
+    # @private
+    # @return [Boolean]
+    attr_reader :recursive
+
+    # Calls this Watcher's callback with the given {Event}.
+    #
+    # @private
+    # @param event [Event]
+    def callback!(event)
+      @callback[event]
+    end
+
+    # Disables this Watcher, so that it doesn't fire any more events.
+    #
+    # @raise [SystemCallError] if the watch fails to be disabled for some reason
+    def close
+      r = Native.k32FindCloseChangeNotification(@id)
+      #@notifier.remove_watcher(self)
+      return if r == 0
+      raise SystemCallError.new("Failed to stop watching #{@path.inspect}", r)
+    end
+
+    # Creates a new {Watcher}.
+    #
+    # @private
+    # @see Notifier#watch
+    def initialize(notifier, path, recursive, *flags, &callback)
+      @notifier = notifier
+      @callback = callback || proc {}
+      @path = path
+      @flags = flags
+      @recursive = recursive
+      @id = Native.k32FindFirstChangeNotification(path, recursive,
+        Native::Flags.to_mask(flags));
+ 
+      unless @id < 0
+        @notifier.add_watcher(self)
+        return
+      end
+
+      raise SystemCallError.new("Failed to watch #{path.inspect}", @id)
+    end
+  end
+end

data/rb-fchange.gemspec

@@ -0,0 +1,32 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "rb-fchange/version"
+
+Gem::Specification.new do |s|
+  s.name        = %q{rb-fchange}
+  s.version     = FChange::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors 	= ["stereobooster"]
+  s.date = %q{2011-04-28}
+  s.description = %q{A Ruby wrapper for Windows Kernel functions for monitoring the specified directory or subtree}
+  s.email = %q{stereobooster@gmail.com}
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.files = [
+    "README.md",
+    "Rakefile",
+    "lib/rb-fchange.rb",
+    "lib/rb-fchange/event.rb",
+    "lib/rb-fchange/native.rb",
+    "lib/rb-fchange/native/flags.rb",
+    "lib/rb-fchange/notifier.rb",
+    "lib/rb-fchange/watcher.rb",
+    "rb-fchange.gemspec"
+  ]
+  s.homepage = %q{http://github.com/stereobooster/rb-fchange}
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{A Ruby wrapper for Windows Kernel functions for monitoring the specified directory or subtree}
+  s.add_dependency('win32-api', '>= 1.4.8')
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification 
+name: rb-fchange
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 2
+  version: 0.0.2
+platform: ruby
+authors: 
+- stereobooster
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-28 00:00:00 +03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: win32-api
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 4
+        - 8
+        version: 1.4.8
+  type: :runtime
+  version_requirements: *id001
+description: A Ruby wrapper for Windows Kernel functions for monitoring the specified directory or subtree
+email: stereobooster@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- README.md
+- Rakefile
+- lib/rb-fchange.rb
+- lib/rb-fchange/event.rb
+- lib/rb-fchange/native.rb
+- lib/rb-fchange/native/flags.rb
+- lib/rb-fchange/notifier.rb
+- lib/rb-fchange/watcher.rb
+- rb-fchange.gemspec
+has_rdoc: true
+homepage: http://github.com/stereobooster/rb-fchange
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: A Ruby wrapper for Windows Kernel functions for monitoring the specified directory or subtree
+test_files: []
+