rb-kqueue-burke 0.1.0

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/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Nathan Weizenbaum
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,44 @@
+# rb-kqueue
+
+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).
+
+## WARNING
+
+This code is incomplete, and didn't work last I had a chance to test it.
+I don't have time to continue working on it at the moment,
+so I'm posting it online for posterity and in case anyone wants to take a crack at it.
+
+If anyone wants commit rights, just email me at nex342@gmail.com.
+
+## 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

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "rb-kqueue"
+    gem.summary = "A Ruby wrapper for BSD's kqueue, using FFI"
+    gem.description = gem.summary
+    gem.email = "nex342@gmail.com"
+    gem.homepage = "http://github.com/nex3/rb-kqueue"
+    gem.authors = ["Nathan Weizenbaum"]
+    gem.add_dependency "ffi", ">= 0.5.0"
+    gem.add_development_dependency "yard", ">= 0.4.0"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+module Jeweler::VersionHelper::PlaintextExtension
+  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_kqueue, :write
+  alias_method :write, :write_with_kqueue
+end
+
+class Jeweler::Commands::Version::Base
+  def commit_version_with_kqueue
+    return unless self.repo
+    self.repo.add(File.join(File.dirname(__FILE__), "lib/rb-kqueue.rb"))
+    commit_version_without_kqueue
+  end
+  alias_method :commit_version_without_kqueue, :commit_version
+  alias_method :commit_version, :commit_version_with_kqueue
+end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/rb-kqueue.rb

@@ -0,0 +1,40 @@
+require 'rb-kqueue/native'
+require 'rb-kqueue/native/flags'
+require 'rb-kqueue/watcher'
+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, 1, 0]
+
+  # 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" +
+      case errno
+      when Errno::EFAULT::Errno; ": There was an error reading or writing the kevent structure."
+      when Errno::EBADF::Errno; ": The specified descriptor is invalid."
+      when Errno::EINTR::Errno; ": A signal was delivered before the timeout expired and before any events were placed on the kqueue for return."
+      when Errno::EINVAL::Errno; ": The specified time limit or filter is invalid."
+      when Errno::ENOENT::Errno; ": The event could not be found to be modified or deleted."
+      when Errno::ENOMEM::Errno; ": No memory was available to register the event."
+      when Errno::ESRCH::Errno; ": The specified process to attach to does not exist."
+      else; ""
+      end,
+      errno)
+  end
+end

data/lib/rb-kqueue/event.rb

@@ -0,0 +1,83 @@
+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_#{filter.to_s.upcase}", @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
+      @data = @native[:data]
+      @filter = KQueue::Native::Flags.from_flag("EVFILT", @native[:filter])
+      @flags = Native::Flags.from_mask("EV", @native[:flags])
+
+      KQueue.handle_error @native[:data] if @flags.include?(: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
+  end
+end

data/lib/rb-kqueue/native.rb

@@ -0,0 +1,41 @@
+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
+    ffi_lib FFI::Library::LIBC
+
+    # The C struct describing a kqueue event.
+    #
+    # @private
+    class KEvent < FFI::Struct
+      layout(
+        :ident,  :uintptr_t,
+        :filter, :int16,
+        :flags,  :uint16,
+        :fflags, :uint32,
+        :data,   :intptr_t,
+        :udata,  :pointer)
+    end
+
+    # The C struct describing a timeout.
+    #
+    # @private
+    class TimeSpec < FFI::Struct
+      layout(
+        :tv_sec, :time_t,
+        :tv_nsec, :long)
+    end
+
+    attach_function :kqueue, [], :int
+    attach_function :kevent, [:int, :pointer, :int, :pointer, :int, :pointer], :int
+
+    attach_function :open, [:string, :int], :int
+    attach_function :close, [:int], :int
+  end
+end

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

@@ -0,0 +1,114 @@
+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
+      EVFILT_WRITE = -2
+      EVFILT_AIO = -3 # Attached to aio requests
+      EVFILT_VNODE = -4 # Attached to vnodes
+      EVFILT_PROC = -5 # Attached to struct proc
+      EVFILT_SIGNAL = -6 # Attached to struct proc
+      EVFILT_TIMER = -7 # Timers
+      EVFILT_MACHPORT = -8 # Mach portsets
+      EVFILT_FS = -9 # Filesystem events
+      EVFILT_USER = -10 # User events
+      EVFILT_SESSION = -11 # Audit session events
+
+
+      # Actions
+      EV_ADD = 0x0001 # Add event to kq (implies enable)
+      EV_DELETE = 0x0002 # Delete event from kq
+      EV_ENABLE = 0x0004 # Enable event
+      EV_DISABLE = 0x0008 # Disable event (not reported)
+      EV_RECEIPT = 0x0040 # Force EV_ERROR on success, data == 0
+
+      # Flags
+      EV_ONESHOT = 0x0010 # Only report one occurrence
+      EV_CLEAR = 0x0020 # Clear event state after reporting
+      EV_DISPATCH = 0x0080 # Disable event after reporting
+
+      # Returned values
+      EV_EOF = 0x8000 # EOF detected
+      EV_ERROR = 0x4000 # Error, data contains errno
+
+
+      # For `EVFILT_{READ,WRITE}`
+      NOTE_READ_LOWAT = NOTE_WRITE_LOWAT = 0x00000001 # Low water mark
+
+      # For `EVFILT_VNODE`
+      NOTE_VNODE_DELETE = 0x00000001 # Vnode was removed
+      NOTE_VNODE_WRITE = 0x00000002 # Data contents changed
+      NOTE_VNODE_EXTEND = 0x00000004 # Size increased
+      NOTE_VNODE_ATTRIB = 0x00000008 # Attributes changed
+      NOTE_VNODE_LINK = 0x00000010 # Link count changed
+      NOTE_VNODE_RENAME = 0x00000020 # Vnode was renamed
+      NOTE_VNODE_REVOKE = 0x00000040 # Vnode access was revoked
+
+      # For `EVFILT_PROC`
+      NOTE_PROC_EXIT = 0x80000000 # Process exited
+      NOTE_PROC_FORK = 0x40000000 # Process forked
+      NOTE_PROC_EXEC = 0x20000000 # Process exec'd
+      NOTE_PROC_REAP = 0x10000000 # Process reaped
+      NOTE_PROC_SIGNAL = 0x08000000 # Received signal
+      NOTE_PROC_TRACK = 0x00000001 # follow across forks
+      NOTE_PROC_TRACKERR = 0x00000002 # could not track child
+      NOTE_PROC_CHILD = 0x00000004 # am a child process
+
+      # For `EVFILT_TIMER`
+      NOTE_TIMER_SECONDS = 0x00000001 # data is seconds
+      NOTE_TIMER_USECONDS = 0x00000002 # data is microseconds
+      NOTE_TIMER_NSECONDS = 0x00000004 # data is nanoseconds
+      NOTE_TIMER_ABSOLUTE = 0x00000008 # absolute timeout
+
+
+      # Converts a list of flags to the bitmask that the C API expects.
+      #
+      # @param prefix [String] The prefix for the C names of the flags
+      # @param flags [Array<Symbol>]
+      # @return [Fixnum]
+      def self.to_mask(prefix, flags)
+        flags.map {|flag| const_get("#{prefix}_#{flag.to_s.upcase}")}.
+          inject(0) {|mask, flag| mask | flag}
+      end
+
+      # Converts a bitmask from the C API into a list of flags.
+      #
+      # @param prefix [String] The prefix for the C names of the flags
+      # @param mask [Fixnum]
+      # @return [Array<Symbol>]
+      def self.from_mask(prefix, mask)
+        re = /^#{Regexp.quote prefix}_/
+        constants.select do |c|
+          next false unless c =~ re
+          const_get(c) & mask != 0
+        end.map {|c| c.to_s.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|
+          next unless c =~ re
+          return c.to_s.sub("#{prefix}_", "").downcase.to_sym if const_get(c) == flag
+        end
+      end
+    end
+  end
+end

data/lib/rb-kqueue/queue.rb

@@ -0,0 +1,365 @@
+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
+
+    # Watches a stream and produces an event when there's data available to read.
+    #
+    # This can watch files, pipes, fifos, and BPF devices.
+    # 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.
+    #
+    # For BPF devices (not supported under Darwin/OS X),
+    # an event is fired when the BPF buffer is full,
+    # the BPF timeout has expired,
+    # or when the BPF has "immediate mode" enabled
+    # and there is data to read.
+    # The {Event#data} field is set to the number of bytes available.
+    #
+    # Note that this isn't compatible with JRuby
+    # unless a native-code file descriptor is passed in.
+    # This means the file descriptor must be returned by an FFI-wrapped C function.
+    #
+    # @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)
+      Watcher::ReadWrite.new(self, fd, :read, callback)
+    end
+
+    # 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.
+    #
+    # Note that this isn't compatible with JRuby
+    # unless a native-code file descriptor is passed in.
+    # This means the file descriptor must be returned by an FFI-wrapped C function.
+    #
+    # @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)
+      Watcher::SocketReadWrite.new(self, fd, :read, low_water, callback)
+    end
+
+    # 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.
+    #
+    # Note that this isn't compatible with JRuby
+    # unless a native-code file descriptor is passed in.
+    # This means the file descriptor must be returned by an FFI-wrapped C function.
+    #
+    # @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)
+      Watcher::ReadWrite.new(self, fd, :write, callback)
+    end
+
+    # 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.
+    #
+    # Note that this isn't compatible with JRuby
+    # unless a native-code file descriptor is passed in.
+    # This means the file descriptor must be returned by an FFI-wrapped C function.
+    #
+    # @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)
+      Watcher::SocketReadWrite.new(self, fd, :write, low_water, callback)
+    end
+
+    # 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
+
+    # 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.
+    #   This is only supported under Darwin/OS X.
+    #
+    # `:reap`
+    # : The process was reaped by the parent via `wait(2)` or similar.
+    #   This is only supported under Darwin/OS X.
+    #
+    # `:track`
+    # : Follow the process across `fork(2)` calls.
+    #   {Event#flags} for the parent process will contain `:fork`,
+    #   while {Event#flags} for the child process will contain `:child`.
+    #   If the system was unable to attach an event to the child process,
+    #   {Event#flags} will contain `:trackerr`.
+    #   This is not supported under Darwin/OS X.
+    #
+    # @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
+
+    # Watches for signals to this process.
+    # This coexists with other signal facilities, and has lower precedence.
+    # Only signals sent to the process, not to a particular thread, will fire events.
+    # Event notification happens before normal signal delivery processing.
+    #
+    # The {Event#data} field contains the number of times the signal has been generated
+    # since the last time the event was fired.
+    #
+    # @param signal [String, Fixnum] The name of number of the signal.
+    # @yield [event] A block that will be run when the signal is received.
+    # @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_for_signal(signal, &callback)
+      Watcher::Signal.new(self, signal, callback)
+    end
+
+    # Sets up a watcher that fires an event
+    # once every specified interval.
+    #
+    # The {Event#data} field contains the number of times the interval has passed
+    # since the last time the event was fired.
+    #
+    # @param time [Number] The interval, in seconds.
+    # @yield [event] A block that will be run when the interval passes.
+    # @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_timer(time, &callback)
+      Watcher::Timer.new(self, time, 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
+
+    def poll
+      read_events(false).each {|event| event.callback!}
+    end
+
+    NULL_TIMEOUT = Native::TimeSpec.new.tap { |ts|
+      ts[:tv_sec] = 0
+      ts[:tv_nsec] = 0
+    }
+
+    # 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(blocking = true)
+      size = 1024
+      eventlist = FFI::MemoryPointer.new(Native::KEvent, size)
+
+      timeout = blocking ? nil : NULL_TIMEOUT
+      res = Native.kevent(@fd, nil, 0, eventlist, size, timeout)
+
+      KQueue.handle_error if res < 0
+      (0...res).map {|i| KQueue::Event.new(Native::KEvent.new(eventlist[i]), self)}
+    end
+  end
+end

data/lib/rb-kqueue/watcher.rb

@@ -0,0 +1,124 @@
+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
+      @filter = filter
+      @flags = []
+      @fflags = fflags
+      @data = data
+      @callback = callback
+      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!
+      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!
+      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!
+      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!
+      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
+      native[:filter] = Native::Flags.to_flag("EVFILT", @filter)
+      native[:flags] = Native::Flags.to_mask("EV", @flags | flags)
+      native[:fflags] = Native::Flags.to_mask("NOTE_#{@filter.to_s.upcase}", @fflags)
+      native[:data] = @data if @data
+      native
+    end
+
+    # 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
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+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
+        @fd = Native.open(path, 0) # 0 means "read only"
+
+        if @fd < 0
+          raise SystemCallError.new(
+            "Failed to open file #{path}" +
+            case FFI.errno
+            when Errno::EACCES::Errno; ": Permission denied."
+            when Errno::EAGAIN::Errno; ": Slave side of a locked pseudo-terminal device."
+            when Errno::EFAULT::Errno; ": Outside the process's allocated address space."
+            when Errno::EINTR::Errno; ": Interrupted."
+            when Errno::ELOOP::Errno; ": Too many symbolic links (possible loop)."
+            when Errno::EMFILE::Errno; ": Too many open files."
+            when Errno::ENAMETOOLONG::Errno; ": Name too long."
+            when Errno::ENFILE::Errno; ": System file table is full."
+            when Errno::ENOENT::Errno; ": File doesn't exist."
+            when Errno::ENOTDIR::Errno; ": A component of the path prefix is not a directory."
+            when Errno::ENXIO::Errno; ": The device associated with this file doesn't exist."
+            when Errno::EOPNOTSUPP::Errno; ": File type not supported."
+            when Errno::EOVERFLOW::Errno; ": File too big."
+            else; ""
+            end,
+            FFI.errno)
+        end
+
+        ObjectSpace.define_finalizer(self, lambda do
+            next unless Native.close(@fd) < 0
+            raise SystemCallError.new(
+              "Failed to close file #{path}" +
+              case FFI.errno
+              when Errno::EBADF::Errno; ": Invalid file descriptor."
+              when Errno::EINTR::Errno; ": Closing interrupted."
+              when Errno::EIO::Errno; ": IO error."
+              else; ""
+              end,
+              FFI.errno)
+          end)
+        super(queue, @fd, :vnode, flags, nil, callback)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+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)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+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 Ruby IO object from which the file descriptor was extracted.
+      # This is only set if an IO object was used to construct this watcher.
+      # Otherwise, it's `nil`.
+      #
+      # @return [IO, nil]
+      attr_reader :io
+
+      # 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)
+        if fd.is_a?(IO)
+          @io = fd
+          fd = fd.fileno
+        end
+
+        @fd = fd
+        @type = type
+        super(queue, @fd, type, [], nil, callback)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+module KQueue
+  class Watcher
+    # The {Watcher} subclass for events fired when a signal is received.
+    # Signal events are watched via {Queue#watch_for_signal}.
+    class Signal < Watcher
+      # The name of the signal, e.g. "KILL" for SIGKILL.
+      #
+      # @return [String]
+      attr_reader :name
+
+      # The number of the signal, e.g. 9 for SIGKILL.
+      #
+      # @return [Fixnum]
+      attr_reader :number
+
+      # Creates a new signal Watcher.
+      #
+      # @private
+      def initialize(queue, signal, callback)
+        if signal.is_a?(String)
+          @name = signal
+          @number = Signal.list[signal]
+        else
+          @name = Signal.list.find {|_, n| n == signal}.first
+          @number = signal
+        end
+
+        super(queue, @number, :signal, [], nil, callback)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+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)
+        if fd.is_a?(IO)
+          @io = fd
+          fd = fd.fileno
+        end
+
+        @fd = fd
+        @type = type
+
+        if low_water
+          fflags = [:lowat]
+          data = low_water
+        else
+          fflags = []
+          data = nil
+        end
+
+        super(queue, @fd, type, fflags, data, callback)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+module KQueue
+  class Watcher
+    # The {Watcher} subclass for events fired based on a timer.
+    # Timer events are watched via {Queue#watch_timer}.
+    class Timer < Watcher
+      # The interval on which the timer fires an event, in seconds.
+      #
+      # @return [Numeric]
+      attr_reader :time
+
+      # Creates a new timer Watcher.
+      #
+      # @private
+      def initialize(time, callback)
+        time, unit =
+          if time < 10**-3
+            [(time * 10**9).round, :nseconds]
+          elsif time < 1
+            [(time * 10**6).round, :useconds]
+          elsif time < 10**3 && !time.is_a?(Fixnum)
+            [(time * 10**3).round, nil] # milliseconds
+          else
+            [time.round, :seconds]
+          end
+
+        super(queue, time, :timer, Array(unit), nil, callback)
+      end
+    end
+  end
+end

data/rb-kqueue-burke.gemspec

@@ -0,0 +1,61 @@
+# 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-burke}
+  s.version = "0.1.0"
+
+  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/signal.rb",
+     "lib/rb-kqueue/watcher/socket_read_write.rb",
+     "lib/rb-kqueue/watcher/timer.rb",
+     "rb-kqueue-burke.gemspec"
+  ]
+  s.homepage = %q{http://github.com/burke/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

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: rb-kqueue-burke
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Nathan Weizenbaum
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2010-02-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: &70244761446700 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *70244761446700
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &70244761445980 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :development
+  prerelease: false
+  version_requirements: *70244761445980
+description: A Ruby wrapper for BSD's kqueue, using FFI
+email: nex342@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+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/signal.rb
+- lib/rb-kqueue/watcher/socket_read_write.rb
+- lib/rb-kqueue/watcher/timer.rb
+- rb-kqueue-burke.gemspec
+homepage: http://github.com/burke/rb-kqueue
+licenses: []
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: A Ruby wrapper for BSD's kqueue, using FFI
+test_files: []