rb-kqueue 0.0.1 → 0.0.2

data/.gitignore

@@ -0,0 +1,3 @@
+/pkg
+/.yardoc
+/doc

data/.yardopts

@@ -0,0 +1,5 @@
+--readme          README.md
+--markup          markdown
+--markup-provider maruku
+--hide-void-return
+--no-private

data/README.md

@@ -3,3 +3,34 @@
 This is a simple wrapper over the [kqueue](http://en.wikipedia.org/wiki/Kqueue)
 BSD event notification interface (supported on FreeBSD, NetBSD, OpenBSD, and Darwin).
 It uses the [FFI](http://wiki.github.com/ffi/ffi) gem to avoid having to compile a C extension.
+
+[API documentation is available on rdoc.info](http://rdoc.info/projects/nex3/rb-kqueue).
+
+## Usage
+
+The API is similar to the kqueue C API, but with a more Rubyish feel.
+First, create a queue:
+
+    queue = KQueue::Queue.new
+
+Then, tell it to watch the events you're interested in:
+
+    queue.watch_file("path/to/foo.txt", :write) {puts "foo.txt was modified!"}
+    queue.watch_process(Process.pid, :fork, :exec) do |event|
+      puts "This process has #{event.flags.map {|f| f.to_s + "ed"}.join(" and ")}"
+    end
+
+KQueue can monitor for all sorts of events.
+For a full list, see the `watch_*` methods on {Queue}.
+
+Finally, run the queue:
+
+    queue.run
+
+This will loop infinitely, calling the appropriate callbacks when the events are fired.
+If you don't want infinite looping,
+you can also block until there are available events,
+process them all at once,
+and then continue on your merry way:
+
+    queue.process

data/Rakefile

@@ -19,26 +19,26 @@ rescue LoadError
 end
 
 module Jeweler::VersionHelper::PlaintextExtension
-  def write_with_inotify
-    write_without_inotify
+  def write_with_kqueue
+    write_without_kqueue
     filename = File.join(File.dirname(__FILE__), "lib/rb-kqueue.rb")
     text = File.read(filename)
     File.open(filename, 'w') do |f|
       f.write text.gsub(/^(  VERSION = ).*/, '\1' + [major, minor, patch].inspect)
     end
   end
-  alias_method :write_without_inotify, :write
-  alias_method :write, :write_with_inotify
+  alias_method :write_without_kqueue, :write
+  alias_method :write, :write_with_kqueue
 end
 
 class Jeweler::Commands::Version::Base
-  def commit_version_with_inotify
+  def commit_version_with_kqueue
     return unless self.repo
     self.repo.add(File.join(File.dirname(__FILE__), "lib/rb-kqueue.rb"))
-    commit_version_without_inotify
+    commit_version_without_kqueue
   end
-  alias_method :commit_version_without_inotify, :commit_version
-  alias_method :commit_version, :commit_version_with_inotify
+  alias_method :commit_version_without_kqueue, :commit_version
+  alias_method :commit_version, :commit_version_with_kqueue
 end
 
 begin

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/lib/rb-kqueue.rb

@@ -1,15 +1,27 @@
 require 'rb-kqueue/native'
 require 'rb-kqueue/native/flags'
 require 'rb-kqueue/watcher'
-require 'rb-kqueue/watcher/vnode'
+require 'rb-kqueue/watcher/file'
 require 'rb-kqueue/watcher/read_write'
 require 'rb-kqueue/watcher/process'
 require 'rb-kqueue/event'
 require 'rb-kqueue/queue'
 
+# The root module of the library, which is laid out as so:
+#
+# * {Queue} -- The main class, where events are registered
+# * {Watcher} -- A watcher for a single sort of event
+# * {Event} -- A notification that an event has occurred
 module KQueue
-  VERSION = [0, 0, 1]
+  VERSION = [0, 0, 2]
 
+  # Raise an exception for a native kqueue error.
+  #
+  # @param errno [Fixnum] The errno identifying the sort of error.
+  #   This is usually C's `errno` variable,
+  #   but is sometimes set in a kevent struct
+  # @raise [SystemCallError]
+  # @private
   def self.handle_error(errno = FFI.errno)
     raise SystemCallError.new(
       "KQueue failed" +

data/lib/rb-kqueue/event.rb

@@ -1,20 +1,65 @@
 module KQueue
+  # An event produced by kqueue.
+  # Each {Watcher} can fire many events,
+  # which are passed to that Watcher's callback.
   class Event
+    # Some integer data, the interpretation of which
+    # is specific to each individual {Watcher}.
+    # For specifics, see the individual Watcher subclasses.
+    #
+    # `data` is not meaningful for all events.
+    # For example, file-change notifications do not set `data`.
+    #
+    # @return [Fixnum]
     attr_reader :data
+
+    # The name of the kqueue filter that created this event,
+    # e.g. `:vnode` or `:read`.
+    #
+    # @private
+    # @return [Symbol]
     attr_reader :filter
 
+    # The {Watcher} that produced this event.
+    #
+    # @return [Watcher]
     def watcher
       @watcher ||= @queue.watchers[[filter, @native[:ident]]]
     end
 
+    # An array of flags, the interpretation of which
+    # is specific to each individual {Watcher}.
+    #
+    # If the Watcher watches for different sorts of events,
+    # this is usually the specific events that actually occurred.
+    # For example, for file-change notifications this could be `[:delete]`.
+    #
+    # `flags` is not meaningful for all events.
+    # For example, readability notifications do not set `flags`.
+    #
+    # @return [Array<Symbol>]
     def flags
       @fflags ||= Native::Flags.from_mask("NOTE", @native[:fflags])
     end
 
+    # Returns whether the end-of-file flag has been set for this event.
+    # The interpretation of this is specific to each individual {Watcher}.
+    #
+    # `eof?` is not meaningful for all events.
+    # For example, file-change notifications don't set `eof?`.
+    #
+    # @return [Boolean]
     def eof?
       @flags.include?(:eof)
     end
 
+    # Creates a new event from a native event structure.
+    #
+    # @private
+    # @param native [Native::Event] The native event structure
+    #   from which to construct this event
+    # @param queue [Queue] The queue that produced this event
+    # @raise [SystemCallError] If this event signals an error
     def initialize(native, queue)
       @native = native
       @queue = queue
@@ -25,6 +70,12 @@ module KQueue
       KQueue.handle_error @native[:data] if @flags.inclue?(:error)
     end
 
+    # Runs the callback for this event.
+    # This callback is associated with the {Watcher}
+    # that produced the event.
+    #
+    # @private
+    # @return [void]
     def callback!
       watcher.callback! self
     end

data/lib/rb-kqueue/native.rb

@@ -1,9 +1,17 @@
 require 'ffi'
 
 module KQueue
+  # This module contains the low-level foreign-function interface code
+  # for dealing with the kqueue C APIs.
+  # It's an implementation detail, and not meant for users to deal with.
+  #
+  # @private
   module Native
     extend FFI::Library
 
+    # The C struct describing a kqueue event.
+    #
+    # @private
     class KEvent < FFI::Struct
       layout(
         :ident,  :uintptr_t,
@@ -14,6 +22,9 @@ module KQueue
         :udata,  :pointer)
     end
 
+    # The C struct describing a timeout.
+    #
+    # @private
     class TimeSpec < FFI::Struct
       layout(
         :tv_sec, :time_t,

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

@@ -1,5 +1,9 @@
 module KQueue
   module Native
+    # A module containing all the C-level integer flags
+    # that are used with kqueue.
+    #
+    # @private
     module Flags
       # Filters
       EVFILT_READ = -1
@@ -32,10 +36,10 @@ module KQueue
       EV_ERROR = 0x4000 # Error, data contains errno
 
 
-      # For EVFILT_{READ,WRITE}
+      # For `EVFILT_{READ,WRITE}`
       NOTE_LOWAT = 0x00000001 # Low water mark
 
-      # For EVFILT_VNODE
+      # For `EVFILT_VNODE`
       NOTE_DELETE = 0x00000001 # Vnode was removed
       NOTE_WRITE = 0x00000002 # Data contents changed
       NOTE_EXTEND = 0x00000004 # Size increased
@@ -43,7 +47,13 @@ module KQueue
       NOTE_LINK = 0x00000010 # Link count changed
       NOTE_RENAME = 0x00000020 # Vnode was renamed
       NOTE_REVOKE = 0x00000040 # Vnode access was revoked
-      NOTE_NONE = 0x00000080 # No specific vnode event: to test for EVFILT_READ activation
+
+      # For `EVFILT_PROC`
+      NOTE_EXIT = 0x80000000 # Process exited
+      NOTE_FORK = 0x40000000 # Process forked
+      NOTE_EXEC = 0x20000000 # Process exec'd
+      NOTE_REAP = 0x10000000 # Process reaped
+      NOTE_SIGNAL = 0x08000000 # Received signal
 
 
       # Converts a list of flags to the bitmask that the C API expects.
@@ -69,10 +79,20 @@ module KQueue
         end.map {|c| c.sub("#{prefix}_", "").downcase.to_sym}
       end
 
+      # Converts a flag to the integer that the C API expects.
+      #
+      # @param prefix [String] The prefix for the C names of the flags
+      # @param flag [Symbol]
+      # @return [Fixnum]
       def self.to_flag(prefix, flag)
         const_get("#{prefix}_#{flag.to_s.upcase}")
       end
 
+      # Converts an integer from the C API into a flag.
+      #
+      # @param prefix [String] The prefix for the C names of the flags
+      # @param flag [Fixnum]
+      # @return [Symbol]
       def self.from_flag(prefix, flag)
         re = /^#{Regexp.quote prefix}_/
         constants.each do |c|

data/lib/rb-kqueue/queue.rb

@@ -1,54 +1,284 @@
 module KQueue
+  # Queue wraps a single instance of kqueue.
+  # It's possible to have more than one instance,
+  # but usually unnecessary.
+  #
+  # New event watchers are added to a queue
+  # via various `watch_*` methods.
+  # For example, \{#watch\_stream\_for\_read} watches for a stream
+  # to become readable, and \{#watch\_file} watches for a file to change.
+  #
+  # Once watchers are added, \{#run} or \{#process} can be used to fire events.
+  # Note that if any event-causing conditions happen
+  # between adding a watcher and running one of these methods,
+  # these events are also fired once the methods are called.
+  #
+  # @example
+  #   # Create the queue
+  #   queue = KQueue::Queue.new
+  #
+  #   # Run this callback whenever the file path/to/foo.txt is read
+  #   queue.watch_file("path/to/foo.txt", :write) do
+  #     puts "Foo.txt was modified!"
+  #   end
+  #
+  #   # Run this callback whenever this process forks or execs
+  #   queue.watch_process(Process.pid, :fork, :exec) do |event|
+  #     # The #flags field of the event object contains the actions that happened
+  #     puts "This process has #{event.flags.map {|f| f.to_s + "ed"}.join(" and ")}"
+  #   end
+  #
+  #   # Nothing happens until you run the queue!
+  #   queue.run
   class Queue
+    # The file descriptor of the kqueue.
+    #
+    # @private
+    # @return [Fixnum]
     attr_reader :fd
+
+    # A hash from filter names and idents to {Watcher}s.
+    # The kqueue API guarantees that a (filter, ident) pair
+    # uniquely identifies a watcher.
+    #
+    # This hash allows events to retrieve their watchers.
+    #
+    # @private
+    # @return [{(Symbol, Fixnum) => Watcher}]
     attr_reader :watchers
 
+    # Creates a new, empty queue.
     def initialize
       @fd = Native.kqueue
       @watchers = {}
     end
 
-    def watch_for_read(fd, &callback)
+    # Watches a stream and produces an event when there's data available to read.
+    #
+    # This can watch files, pipes, and fifos.
+    # For files, an event is fired whenever the file pointer
+    # is not at the end of the file,
+    # and the {Event#data} field is set to the offset
+    # from the current position to the end of the file.
+    # {Event#data} may be negative.
+    #
+    # For pipes and fifos, an event is fired whenever there's data to read.
+    # The {Event#data} field is set to the number of bytes available.
+    # When the last writer disconnects, {Event#eof?} will be set.
+    #
+    # @param fd [IO, Fixnum] A Ruby IO stream, or the file descriptor
+    #   for a native IO stream.
+    # @yield [event] A block that will be run when the specified stream
+    #   has data to read.
+    # @yieldparam event [Event] The Event object containing information
+    #   about the event that occurred.
+    # @return [Watcher] The Watcher for this event.
+    # @raise [SystemCallError] If something goes wrong when registering the Watcher.
+    def watch_stream_for_read(fd, &callback)
       fd = fd.fileno if fd.respond_to?(:fileno)
       Watcher::ReadWrite.new(self, fd, :read, callback)
     end
 
-    def watch_for_socket_read(fd, low_water = nil, &callback)
+    # Watches a socket and produces an event when there's data available to read.
+    #
+    # Sockets which have previously had `Socket#listen` called fire events
+    # when there is an incoming connection pending.
+    # In this case, {Event#data} contains the size of the listen backlog.
+    #
+    # Other sockets return when there is data to be read,
+    # subject to the SO_RCVLOWAT value of the socket buffer.
+    # This may be overridden via the `low_water` parameter,
+    # which sets a new low-water mark.
+    # In this case, {Event#data} contains the number of bytes
+    # of protocol data available to read.
+    #
+    # If the read direction of the socket has shut down,
+    # then {Event#eof?} is set.
+    # It's possible for {Event#eof?} to be set while there's still
+    # data pending in the socket buffer.
+    #
+    # @param fd [Socket, Fixnum] A Ruby Socket, or the file descriptor
+    #   for a native Socket.
+    # @param low_water [Fixnum] The low-water mark for new data.
+    # @yield [event] A block that will be run when the specified socket
+    #   has data to read.
+    # @yieldparam event [Event] The Event object containing information
+    #   about the event that occurred.
+    # @return [Watcher] The Watcher for this event.
+    # @raise [SystemCallError] If something goes wrong when registering the Watcher.
+    def watch_socket_for_read(fd, low_water = nil, &callback)
       fd = fd.fileno if fd.respond_to?(:fileno)
       Watcher::SocketReadWrite.new(self, fd, :read, low_water, callback)
     end
 
-    def watch_for_write(fd, &callback)
+    # Watches a stream and produces an event
+    # when it's possible to write to the stream.
+    #
+    # This can watch pipes and fifos.
+    # The {Event#data} field is set to the amount of space
+    # remaining in the write buffer.
+    # When the reader disconnects, {Event#eof?} will be set.
+    #
+    # @param fd [IO, Fixnum] A Ruby IO stream, or the file descriptor
+    #   for a native IO stream.
+    # @yield [event] A block that will be run when the specified stream
+    #   has data to read.
+    # @yieldparam event [Event] The Event object containing information
+    #   about the event that occurred.
+    # @return [Watcher] The Watcher for this event.
+    # @raise [SystemCallError] If something goes wrong when registering the Watcher.
+    def watch_stream_for_write(fd, &callback)
       fd = fd.fileno if fd.respond_to?(:fileno)
       Watcher::ReadWrite.new(self, fd, :write, callback)
     end
 
-    def watch_for_socket_write(fd, low_water = nil, &callback)
+    # Watches a socket and produces an event when it's possible to write.
+    # The {Event#data} field is set to the amount of space
+    # remaining in the write buffer.
+    #
+    # When an event is fired is subject to the
+    # subject to the SO_RCVLOWAT value of the socket buffer.
+    # This may be overridden via the `low_water` parameter,
+    # which sets a new low-water mark.
+    #
+    # If the write direction of the socket has shut down,
+    # then {Event#eof?} is set.
+    # It's possible for {Event#eof?} to be set while there's still
+    # data pending in the socket buffer.
+    #
+    # @param fd [Socket, Fixnum] A Ruby Socket, or the file descriptor
+    #   for a native Socket.
+    # @param low_water [Fixnum] The low-water mark for new data.
+    # @yield [event] A block that will be run when it's possible
+    #   to write to the specified socket.
+    # @yieldparam event [Event] The Event object containing information
+    #   about the event that occurred.
+    # @return [Watcher] The Watcher for this event.
+    # @raise [SystemCallError] If something goes wrong when registering the Watcher.
+    def watch_socket_for_write(fd, low_water = nil, &callback)
       fd = fd.fileno if fd.respond_to?(:fileno)
       Watcher::SocketReadWrite.new(self, fd, :write, low_water, callback)
     end
 
-    def watch_for_file_change(path, *flags, &callback)
-      Watcher::VNode.new(self, path, flags, callback)
+    # Watches a file or directory for changes.
+    # The `flags` parameter specifies which changes
+    # will fire events.
+    #
+    # The {Event#flags} field contains the changes that caused the event to be fired.
+    # {Event#data} and {Event#eof?} are unused.
+    #
+    # Note that this only watches a single file.
+    # If the file is a direcotry,
+    # it will only report changes to the directory itself,
+    # not to any files within the directory.
+    #
+    # ## Flags
+    #
+    # `:delete`
+    # : The file was deleted.
+    #
+    # `:write`
+    # : The file was modified.
+    #
+    # `:extend`
+    # : The size of the file increased.
+    #
+    # `:attrib`
+    # : Attributes of the file, such as timestamp or permissions, changed.
+    #
+    # `:link`
+    # : The link count of the file changed.
+    #
+    # `:rename`
+    # : The file was renamed.
+    #
+    # `:revoke`
+    # : Access to the file was revoked,
+    #   either via the `revoke(2)` system call
+    #   or because the underlying filesystem was unmounted.
+    #
+    # @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 run when the file changes.
+    # @yieldparam event [Event] The Event object containing information
+    #   about the event that occurred.
+    # @return [Watcher] The Watcher for this event.
+    # @raise [SystemCallError] If something goes wrong when registering the Watcher.
+    def watch_file(path, *flags, &callback)
+      Watcher::File.new(self, path, flags, callback)
     end
 
-    def watch_for_process_change(pid, *flags, &callback)
+    # Watches a process for changes.
+    # The `flags` parameter specifies which changes
+    # will fire events.
+    #
+    # The {Event#flags} field contains the changes that caused the event to be fired.
+    # {Event#data} and {Event#eof?} are unused.
+    #
+    # ## Flags
+    #
+    # `:exit`
+    # : The process has exited.
+    #
+    # `:fork`
+    # : The process has created a child process via `fork(2)` or similar.
+    #
+    # `:exec`
+    # : The process has executed a new process via `exec(2)` or similar.
+    #
+    # `:signal`
+    # : The process was sent a signal.
+    #
+    # `:reap`
+    # : The process was reaped by the parent via `wait(2)` or similar.
+    #
+    # @param pid [Fixnum] The id of the process.
+    # @param flags [Array<Symbol>] Which events to watch for.
+    # @yield [event] A block that will be run when the process changes.
+    # @yieldparam event [Event] The Event object containing information
+    #   about the event that occurred.
+    # @return [Watcher] The Watcher for this event.
+    # @raise [SystemCallError] If something goes wrong when registering the Watcher.
+    def watch_process(pid, *flags, &callback)
       Watcher::Process.new(self, path, flags, callback)
     end
 
+    # Starts the queue watching for events.
+    # Blocks until \{#stop} is called.
+    #
+    # @see #process
+    # @return [void]
     def run
       @stop = false
       process until @stop
     end
 
+    # Stop watching for events.
+    # That is, if we're in a \{#run} loop,
+    # exit out as soon as we finish handling
+    # the current batch of events.
+    #
+    # @return [void]
     def stop
       @stop = true
     end
 
+    # Blocks until there are one or more events
+    # that this queue has watchers registered for.
+    # Once there are events, the appropriate callbacks are called
+    # and this function returns.
+    #
+    # @see #run
+    # @return [void]
     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
       size = 1024
       eventlist = FFI::MemoryPointer.new(Native::KEvent, size)

data/lib/rb-kqueue/watcher.rb

@@ -1,7 +1,34 @@
 module KQueue
+  # Watchers monitor for a single sort of event,
+  # specified by the specific subclass and its parameters.
+  # A watcher is usually created via one of the `watch_*` methods
+  # on {Queue}.
+  #
+  # One {Queue} may have many {Watcher}s.
+  # The Queue actually takes care of the checking for events,
+  # via \{Queue#run #run} or \{Queue#process #process}.
+  #
+  # Watcher objects themselves have several useful capabilities.
+  # Each subclass keeps track of its own specific information.
+  # In addition, all Watchers can be \{#delete! deleted from the queue},
+  # \{#add! added back in}, \{#disable! disabled}, and \{#enable! enabled}.
   class Watcher
+    # The {Queue} that created this Watcher.
+    #
+    # @return [Queue]
     attr_reader :queue
 
+    # Creates a new Watcher.
+    #
+    # @private
+    # @param queue [Queue] The queue for which this watcher will be used.
+    # @param ident [Fixnum] The underlying kqueue identifier for this watcher.
+    # @param filter [Symbol] The name of the underlying kqueue filter for this watcher.
+    # @param fflags [Array<Symbol>] Filter-specific flags.
+    # @param data [Fixnum] Filter-specific data.
+    # @param callback [Proc{Event -> void}] The callback that will be called
+    #   on any events fired by this watcher.
+    # @raise [SystemCallError] If something goes wrong when registering this Watcher.
     def initialize(queue, ident, filter, fflags, data, callback)
       @queue = queue
       @ident = ident
@@ -13,30 +40,63 @@ module KQueue
       add!
     end
 
+    # Adds this Watcher to \{#queue its Queue}.
+    # Note that this is done automatically when the Watcher is created.
+    #
+    # @raise [SystemCallError] If something goes wrong when adding this Watcher.
+    # @return [void]
     def add!
-      kqueue! :add, :clear # TODO: Don't always enable :clear
+      kevent! :add, :clear # TODO: Don't always enable :clear
       @queue.watchers[[@filter, @ident]] = self
     end
 
+    # Removes this Watcher from \{#queue its Queue}.
+    # This means that events won't be fired
+    # or even checked for.
+    #
+    # @raise [SystemCallError] If something goes wrong when deleting this Watcher.
+    # @return [void]
     def delete!
-      kqueue! :delete
+      kevent! :delete
       @queue.watchers.delete([@filter, @ident])
     end
 
+    # Enables this Watcher.
+    # Note that this is done automatically when the Watcher is created,
+    # as well as whenever \{#add!} is called.
+    #
+    # @raise [SystemCallError] If something goes wrong when enabling this Watcher.
+    # @return [void]
     def enable!
-      kqueue! :enable
+      kevent! :enable
     end
 
+    # Disables this Watcher.
+    # This means that events won't be fired,
+    # but they'll still be checked for.
+    #
+    # @raise [SystemCallError] If something goes wrong when enabling this Watcher.
+    # @return [void]
     def disable!
-      kqueue! :disable
+      kevent! :disable
     end
 
+    # Calls this Watcher's callback with the given {Event}.
+    #
+    # @private
+    # @param event [Event]
+    # @return [void]
     def callback!(event)
       @callback.call event
     end
 
     private
 
+    # Returns a C struct corresponding to this watcher.
+    #
+    # @param flags [Array<Symbol>] Flags for the C struct's `flags` field,
+    #   in addition to the `@flags` var.
+    # @return [Native::KEvent]
     def native(flags)
       native = Native::KEvent.new
       native[:ident] = @ident
@@ -47,7 +107,15 @@ module KQueue
       native
     end
 
-    def kqueue!(*flags)
+    # Runs the `kevent` C call with this Watcher's kevent struct as input.
+    # This effectively means telling kqueue to perform some action
+    # with this Watcher as an argument.
+    #
+    # @param flags [Array<Symbol>] Flags specifying the action to perform
+    #   as well as any additional flags.
+    # @return [void]
+    # @raise [SystemCallError] If something goes wrong when performing the C call.
+    def kevent!(*flags)
       if Native.kevent(@queue.fd, native(flags).pointer, 1, nil, 0, nil) < 0
         KQueue.handle_error
       end

data/lib/rb-kqueue/watcher/file.rb

@@ -0,0 +1,21 @@
+module KQueue
+  class Watcher
+    # The {Watcher} subclass for events fired when a file changes.
+    # File events are watched via {Queue#watch_file}.
+    class File < Watcher
+      # The path to the file being watched.
+      #
+      # @return [String]
+      attr_reader :path
+
+      # Creates a new file Watcher.
+      #
+      # @private
+      def initialize(queue, path, flags, callback)
+        @path = path
+        @file = File.open(path) # TODO: not JRuby-compatible
+        super(queue, @file.fileno, :vnode, flags, nil, callback)
+      end
+    end
+  end
+end

data/lib/rb-kqueue/watcher/process.rb

@@ -1,8 +1,16 @@
 module KQueue
   class Watcher
+    # The {Watcher} subclass for process events.
+    # Process events are watched via {Queue#watch_process}.
     class Process < Watcher
+      # The process id of the process being watched.
+      #
+      # @return [Fixnum]
       attr_reader :pid
 
+      # Creates a new process Watcher.
+      #
+      # @private
       def initialize(queue, pid, flags, callback)
         @pid = pid
         super(queue, pid, :proc, flags, nil, callback)

data/lib/rb-kqueue/watcher/read_write.rb

@@ -1,9 +1,27 @@
 module KQueue
   class Watcher
+    # The {Watcher} subclass for events
+    # fired when a stream can be read from or written to
+    # (which of these is determined by \{#type}).
+    # Read events are watched via {Queue#watch_stream_for_read},
+    # and write events are watched via {Queue#watch_stream_for_write}.
+    #
+    # Note that read and write events for sockets
+    # use the {SocketReadWrite} class.
     class ReadWrite < Watcher
+      # The file descriptor for the stream being watched.
+      #
+      # @return [Fixnum]
       attr_reader :fd
+
+      # The type of watcher, `:read` or `:write`.
+      #
+      # @return [Symbol]
       attr_reader :type
 
+      # Creates a new read/write Watcher.
+      #
+      # @private
       def initialize(queue, fd, type, callback)
         @fd = fd
         @type = type

data/lib/rb-kqueue/watcher/socket_read_write.rb

@@ -1,8 +1,24 @@
 module KQueue
   class Watcher
+    # The {Watcher} subclass for events
+    # fired when a socket can be read from or written to
+    # (which of these is determined by \{ReadWrite#type}).
+    # Read events are watched via {Queue#watch_socket_for_read},
+    # and write events are watched via {Queue#watch_socket_for_write}.
+    #
+    # Note that read and write events for non-socket streams
+    # use the {ReadWrite} class.
     class SocketReadWrite < ReadWrite
+      # The custom low-water mark for the amount of data necessary
+      # to trigger an event,
+      # or `nil` if none has been set.
+      #
+      # @return [Fixnum, nil]
       attr_reader :low_water
 
+      # Creates a new socket Watcher.
+      #
+      # @private
       def initialize(queue, fd, type, low_water, callback)
         @fd = fd
         @type = type

data/rb-kqueue.gemspec

@@ -0,0 +1,59 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{rb-kqueue}
+  s.version = "0.0.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Nathan Weizenbaum"]
+  s.date = %q{2010-02-08}
+  s.description = %q{A Ruby wrapper for BSD's kqueue, using FFI}
+  s.email = %q{nex342@gmail.com}
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.files = [
+    ".gitignore",
+     ".yardopts",
+     "MIT-LICENSE",
+     "README.md",
+     "Rakefile",
+     "VERSION",
+     "lib/rb-kqueue.rb",
+     "lib/rb-kqueue/event.rb",
+     "lib/rb-kqueue/native.rb",
+     "lib/rb-kqueue/native/flags.rb",
+     "lib/rb-kqueue/queue.rb",
+     "lib/rb-kqueue/watcher.rb",
+     "lib/rb-kqueue/watcher/file.rb",
+     "lib/rb-kqueue/watcher/process.rb",
+     "lib/rb-kqueue/watcher/read_write.rb",
+     "lib/rb-kqueue/watcher/socket_read_write.rb",
+     "rb-kqueue.gemspec"
+  ]
+  s.homepage = %q{http://github.com/nex3/rb-kqueue}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{A Ruby wrapper for BSD's kqueue, using FFI}
+
+  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<ffi>, [">= 0.5.0"])
+      s.add_development_dependency(%q<yard>, [">= 0.4.0"])
+    else
+      s.add_dependency(%q<ffi>, [">= 0.5.0"])
+      s.add_dependency(%q<yard>, [">= 0.4.0"])
+    end
+  else
+    s.add_dependency(%q<ffi>, [">= 0.5.0"])
+    s.add_dependency(%q<yard>, [">= 0.4.0"])
+  end
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rb-kqueue
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Nathan Weizenbaum
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-07 00:00:00 -08:00
+date: 2010-02-08 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -41,6 +41,8 @@ extensions: []
 extra_rdoc_files: 
 - README.md
 files: 
+- .gitignore
+- .yardopts
 - MIT-LICENSE
 - README.md
 - Rakefile
@@ -51,10 +53,11 @@ files:
 - lib/rb-kqueue/native/flags.rb
 - lib/rb-kqueue/queue.rb
 - lib/rb-kqueue/watcher.rb
+- lib/rb-kqueue/watcher/file.rb
 - lib/rb-kqueue/watcher/process.rb
 - lib/rb-kqueue/watcher/read_write.rb
 - lib/rb-kqueue/watcher/socket_read_write.rb
-- lib/rb-kqueue/watcher/vnode.rb
+- rb-kqueue.gemspec
 has_rdoc: true
 homepage: http://github.com/nex3/rb-kqueue
 licenses: []

data/lib/rb-kqueue/watcher/vnode.rb

@@ -1,13 +0,0 @@
-module KQueue
-  class Watcher
-    class VNode < Watcher
-      attr_reader :path
-
-      def initialize(queue, path, flags, callback)
-        @path = path
-        @file = File.open(path) # TODO: not JRuby-compatible
-        super(queue, @file.fileno, :vnode, flags, nil, callback)
-      end
-    end
-  end
-end