yakischloba-ktools 0.0.2

data/README

@@ -0,0 +1,49 @@
+Bringing common kernel APIs into Ruby using FFI.
+http://github.com/yakischloba/ktools
+
+Synopsis:
+
+#  irb(main):001:0> require 'ktools'
+#  => true
+#  irb(main):002:0> r, w = IO.pipe
+#  => [#<IO:0x4fa90c>, #<IO:0x4fa880>]
+#  irb(main):003:0> kq = Kqueue.new
+#  => #<Kernel::Kqueue:0x4f43a4 @kqfd=6, @fds={}>
+#  irb(main):004:0> kq.add(:socket, r, :events => [:read, :write])
+#  => true
+#  irb(main):005:0> kq.poll
+#  => []
+#  irb(main):006:0> w.write "foo"
+#  => 3
+#  irb(main):007:0> kq.poll
+#  => [{:type=>:socket, :target=>#<IO:0x4fa90c>, :event=>:read}]
+#  irb(main):008:0> [r, w, kq].each {|i| i.close}
+
+
+I plan to support the following kernel APIs:
+
+kqueue (works - see tests/test_kqueue.rb)
+epoll (works - see tests/test_epoll.rb. Needs Ruby wrapper.)
+inotify
+netlink
+
+and maybe some others! I will at first hook up the C interfaces as directly 
+as possible, and then write Rubyist-friendly wrappers around them. Kqueue
+currently has a (I think) decent wrapper and epoll is up next.
+
+
+To install:
+
+git clone git://github.com/yakischloba/ktools.git
+cd ktools
+gem build
+sudo gem install ktools-<version>.gem
+
+Also gems are on Rubyforge, so you can simply 'sudo gem install ktools', but commits will
+be frequent for some time, so you'll probably want to be pulling the latest from Github.
+
+Please file all issues on the Github issue tracker. Patches (with tests) are welcome and 
+encouraged, as are suggestions about API design, etc. It's all up in the air right now.
+
+yakischloba on freenode
+jakecdouglas at gmail

data/Rakefile

@@ -0,0 +1,77 @@
+require 'rake' unless defined?(Rake)
+require 'mkmf'
+include Config
+
+task :default => [:build, :test]
+task :build => [:clean, :config, :objs, :shared]
+
+def add_define(name)
+  $ktools_defines.push("-D#{name}")
+end
+
+task :config do
+  $ktools_defines = []
+  $ktools_dlext = RbConfig::expand(CONFIG['DLEXT'])
+  (add_define "HAVE_TBR" and build_against_ruby_stuff = true) if have_func('rb_thread_blocking_region')
+  add_define "HAVE_KQUEUE" if have_header("sys/event.h") and have_header("sys/queue.h")
+  #add_define "HAVE_INOTIFY" if inotify = have_func('inotify_init', 'sys/inotify.h')
+  #add_define "HAVE_OLD_INOTIFY" if !inotify && have_macro('__NR_inotify_init', 'sys/syscall.h')
+
+  if have_header('sys/epoll.h')
+    File.open("hasEpollTest.c", "w") {|f|
+      f.puts "#include <sys/epoll.h>"
+      f.puts "int main() { epoll_create(1024); return 0;}"
+    }
+    (e = system( "gcc hasEpollTest.c -o hasEpollTest " )) and (e = $?.to_i)
+    `rm -f hasEpollTest.c hasEpollTest`
+    add_define 'HAVE_EPOLL' if e == 0
+  end
+
+  $ktools_cc = `which #{RbConfig::expand(CONFIG["CC"])}`.chomp
+  $ktools_cflags = RbConfig::expand(CONFIG['CFLAGS']).split(" ")
+  $ktools_cflags.delete("$(cflags)")
+  $ktools_cflags = $ktools_cflags.join(" ")
+  $ktools_srcs = ["ktools.c"]
+  $ktools_srcs << "kqueue.c" if $ktools_defines.include?("-DHAVE_KQUEUE")
+  $ktools_srcs << "inotify.c" if $ktools_defines.include?("-DHAVE_INOTIFY")
+  $ktools_srcs << "epoll.c" if $ktools_defines.include?("-DHAVE_EPOLL")
+  $ktools_srcs << "netlink.c" if $ktools_defines.include?("-DHAVE_NETLINK")
+
+  if CONFIG["rubyhdrdir"]
+    hdrdir = RbConfig::expand(CONFIG["rubyhdrdir"])
+    $ktools_includes = "-I. -I#{hdrdir}/#{RbConfig::expand(CONFIG["sitearch"])} -I#{hdrdir}" if build_against_ruby_stuff
+  end
+
+  $ktools_ldshared = RbConfig::expand(CONFIG['LDSHARED'])
+  $ktools_ldshared << " -o ../lib/ktools.#{$ktools_dlext} " + $ktools_srcs.collect{|x| x.gsub(/\.c/, ".o")}.join(" ")
+  $ktools_ldshared << " -L#{RbConfig::expand(CONFIG['libdir'])} #{RbConfig::expand(CONFIG['LIBRUBYARG_SHARED'])}" if build_against_ruby_stuff
+end
+
+task :clean do
+  chdir "ext" do
+    sh "rm -f *.o *.bundle *.so"
+  end
+  chdir "lib" do
+    sh "rm -f *.o *.bundle *.so"
+  end
+end
+
+task :test do
+  require 'lib/ktools'
+  require 'bacon'
+  Bacon.summary_on_exit
+  load "tests/test_kqueue.rb" if Kernel.have_kqueue?
+  load "tests/test_epoll.rb" if Kernel.have_epoll?
+end
+
+task :objs do
+  chdir "ext" do
+    $ktools_srcs.each {|c| sh "#{$ktools_cc} #{$ktools_cflags} #{$ktools_defines.join(' ')} #{$ktools_includes} -c #{c}"}
+  end
+end
+
+task :shared do
+  chdir "ext" do
+    sh "#{$ktools_ldshared}"
+  end
+end

data/ext/epoll.c

@@ -0,0 +1,32 @@
+#ifdef HAVE_EPOLL
+
+#include "epoll.h"
+
+#ifdef HAVE_TBR
+#include <ruby.h>
+#endif
+
+int wrap_epoll_wait(int epfd, struct epoll_event *event, int maxevents, int timeout)
+{
+  #ifdef HAVE_TBR
+  struct wrapped_epoll_event epevent;
+  epevent.epfd = epfd;
+  epevent.event = event;
+  epevent.maxevents = maxevents;
+  epevent.timeout = timeout;
+  epevent.result = -1;
+  rb_thread_blocking_region((rb_blocking_function_t *) tbr_epoll_wait, &epevent, RUBY_UBF_IO, 0);
+  return epevent.result;
+  #else
+  return epoll_wait(epfd, event, maxevents, timeout);
+  #endif
+}
+
+#ifdef HAVE_TBR
+void tbr_epoll_wait(struct wrapped_epoll_event *event)
+{
+  event->result = epoll_wait(event->epfd, event->event, event->maxevents, event->timeout);
+}
+#endif
+
+#endif

data/ext/epoll.h

@@ -0,0 +1,17 @@
+#ifdef HAVE_EPOLL
+
+#include <sys/epoll.h>
+
+#ifdef HAVE_TBR
+struct wrapped_epoll_event {
+  int epfd;
+  struct epoll_event *event;
+  int maxevents;
+  int timeout;
+  int result;
+};
+
+void tbr_epoll_wait(struct wrapped_epoll_event*);
+#endif
+
+#endif

data/ext/kqueue.c

@@ -0,0 +1,39 @@
+#ifdef HAVE_KQUEUE
+
+#include "kqueue.h"
+
+#ifdef HAVE_TBR
+#include <ruby.h>
+#endif
+
+void wrap_evset(struct kevent *kev, unsigned int ident, short filter, unsigned short flags, unsigned int fflags, int data, void *udata)
+{
+	EV_SET(kev, ident, filter, flags, fflags, data, udata);
+}
+
+int wrap_kevent(int kqfd, struct kevent *changelist, int nchanges, struct kevent *eventlist, int nevents, struct timespec *timeout)
+{
+  #ifdef HAVE_TBR
+  struct wrapped_kevent wevent;
+  wevent.kqfd = kqfd;
+  wevent.changelist = changelist;
+  wevent.nchanges = nchanges;
+  wevent.eventlist = eventlist;
+  wevent.nevents = nevents;
+  wevent.timeout = timeout;
+  wevent.result = -1;
+  rb_thread_blocking_region((rb_blocking_function_t *) tbr_kevent, &wevent, RUBY_UBF_IO, 0);
+  return wevent.result;
+  #else
+  return kevent(kqfd, changelist, nchanges, eventlist, nevents, timeout);
+  #endif
+}
+
+#ifdef HAVE_TBR
+void tbr_kevent(struct wrapped_kevent *wevent)
+{
+  wevent->result = kevent(wevent->kqfd, wevent->changelist, wevent->nchanges, wevent->eventlist, wevent->nevents, wevent->timeout);
+}
+#endif
+
+#endif

data/ext/kqueue.h

@@ -0,0 +1,20 @@
+#ifdef HAVE_KQUEUE
+
+#include <sys/event.h>
+#include <sys/queue.h>
+
+#ifdef HAVE_TBR
+struct wrapped_kevent {
+  int kqfd;
+  struct kevent *changelist;
+  int nchanges;
+  struct kevent *eventlist;
+  int nevents;
+  struct timespec *timeout;
+  int result;
+};
+
+void tbr_kevent(struct wrapped_kevent*);
+#endif
+
+#endif

data/ext/ktools.c

@@ -0,0 +1,43 @@
+#include "ktools.h"
+#include <errno.h>
+
+int get_errno()
+{
+  return errno;
+}
+
+int have_kqueue()
+{
+	#ifdef HAVE_KQUEUE
+	return 1;
+	#else
+	return 0;
+	#endif
+}
+
+int have_epoll()
+{
+	#ifdef HAVE_EPOLL
+	return 1;
+	#else
+	return 0;
+	#endif
+}
+
+int have_inotify()
+{
+	#ifdef HAVE_INOTIFY
+	return 1;
+	#else
+	return 0;
+	#endif
+}
+
+int have_netlink()
+{
+	#ifdef HAVE_NETLINK
+	return 1;
+	#else
+	return 0;
+	#endif
+}

data/ext/ktools.h

@@ -0,0 +1,20 @@
+#ifndef KTOOLS_H
+#define KTOOLS_H
+
+#ifdef HAVE_EPOLL
+#include "epoll.h"
+#endif
+
+#ifdef HAVE_KQUEUE
+#include "kqueue.h"
+#endif
+
+/*#ifdef HAVE_NETLINK
+#include "netlink.h"
+#endif
+
+#ifdef HAVE_INOTIFY
+#include "inotify.h"
+#endif*/
+
+#endif

data/ktools.gemspec

@@ -0,0 +1,31 @@
+Gem::Specification.new do |s|
+  s.name = "ktools"
+  s.version = "0.0.2"
+  s.date = "2009-04-22"
+  s.authors = ["Jake Douglas"]
+  s.email = "jakecdouglas@gmail.com"
+  s.rubyforge_project = "ktools"
+  s.has_rdoc = true
+  s.add_dependency('ffi')
+  s.add_dependency('bacon')
+  s.summary = "Bringing common kernel APIs into Ruby using FFI"
+  s.homepage = "http://www.github.com/yakischloba/ktools"
+  s.description = "Bringing common kernel APIs into Ruby using FFI"
+  s.extensions = ["Rakefile"]
+  s.files =
+    ["ktools.gemspec",
+    "README",
+    "Rakefile",
+    "lib/ktools.rb",
+    "lib/ktools/ktools.rb",
+    "lib/ktools/epoll.rb",
+    "lib/ktools/kqueue.rb",
+    "ext/ktools.c",
+    "ext/ktools.h",
+    "ext/epoll.c",
+    "ext/epoll.h",
+    "ext/kqueue.c",
+    "ext/kqueue.h",
+    "tests/test_epoll.rb",
+    "tests/test_kqueue.rb"]
+end

data/lib/ktools/epoll.rb

@@ -0,0 +1,203 @@
+module Kernel
+  class Epoll
+    extend FFI::Library
+
+    class Epoll_data < FFI::Struct
+      layout :ptr, :pointer,
+        :fd, :int,
+        :u32, :uint32,
+        :u64, :uint64
+    end
+
+    class Epoll_event < FFI::Struct
+      layout :events, :uint32,
+        :data, :pointer
+
+      def [] key
+        key == :data ? Epoll_data.new(super(key)) : super(key)
+      end
+    end
+
+    epc = FFI::ConstGenerator.new do |c|
+      c.include('sys/epoll.h')
+      c.const("EPOLLIN")
+      c.const("EPOLLPRI")
+      c.const("EPOLLOUT")
+      c.const("EPOLLRDNORM")
+      c.const("EPOLLRDBAND")
+      c.const("EPOLLWRNORM")
+      c.const("EPOLLWRBAND")
+      c.const("EPOLLMSG")
+      c.const("EPOLLERR")
+      c.const("EPOLLHUP")
+      c.const("EPOLLRDHUP")
+      c.const("EPOLLONESHOT")
+      c.const("EPOLLET")
+      c.const("EPOLL_CTL_ADD")
+      c.const("EPOLL_CTL_DEL")
+      c.const("EPOLL_CTL_MOD")
+    end
+
+    eval epc.to_ruby
+
+    EP_FLAGS = {
+      :read => EPOLLIN,
+      :write => EPOLLOUT,
+      :hangup => EPOLLHUP,
+      :priority => EPOLLPRI,
+      :edge => EPOLLET,
+      :oneshot => EPOLLONESHOT,
+      :error => EPOLLERR
+    }
+
+    EP_FLAGS[:remote_hangup] = EPOLLRDHUP if const_defined?("EPOLLRDHUP")
+
+    # Attach directly to epoll_create
+    attach_function :epoll_create, [:int], :int
+    # Attach directly to epoll_ctl
+    attach_function :epoll_ctl, [:int, :int, :int, :pointer], :int
+    # Attach to the epoll_wait wrapper so we can use rb_thread_blocking_region when possible
+    attach_function :epoll_wait, :wrap_epoll_wait, [:int, :pointer, :int, :int], :int
+
+    # Creates a new epoll event queue. Takes an optional size parameter (default 1024) that is a hint
+    # to the kernel about how many descriptors it will be handling. Read man epoll_create for details 
+    # on this. Raises an error if the operation fails.
+    def initialize(size=1024)
+      @fds = {}
+      @epfd = epoll_create(size)
+      raise SystemCallError.new("Error creating epoll descriptor", get_errno) unless @epfd > 0
+    end
+
+    # Generic method for adding events. This simply calls the proper add_foo method specified by the type symbol.
+    # Example:
+    #  ep.add(:socket, sock, :events => [:read])
+    #  calls -> ep.add_socket(sock, events => [:read])
+    #
+    # Note: even though epoll only supports :socket style descriptors, we keep this for consistency with other APIs.
+    def add(type, target, options={})
+      case type
+      when :socket
+        add_socket(target, options)
+      else
+        raise ArgumentError.new("Epoll only supports socket style descriptors")
+      end
+    end
+
+    # Add events to a socket-style descriptor (socket or pipe). Your target can be either
+    # an IO object (socket, pipe), or a file descriptor number.
+    #
+    # Supported :events are:
+    #
+    # * :read - The descriptor has become readable.
+    # * :write - The descriptor has become writeable.
+    # * :priority - There is urgent data available for read operations.
+    # * :error - Error condition happened on the associated file descriptor. (Always active)
+    # * :hangup - Hang up happened on the associated file descriptor. (Always active)
+    # * :remote_hangup - Stream socket peer closed the connection, or shut down writing half of connection. (Missing from some kernel verions)
+    #
+    # Supported :flags are:
+    #
+    # * :edge - Sets the Edge Triggered behavior for the associated file descriptor. (see manpage)
+    # * :oneshot - Sets the one-shot behaviour for the associated file descriptor. (Event only fires once)
+    #
+    # Example:
+    #
+    #  irb(main):001:0> require 'ktools'
+    #  => true
+    #  irb(main):002:0> r, w = IO.pipe
+    #  => [#<IO:0x89be38c>, #<IO:0x89be378>]
+    #  irb(main):003:0> ep = Epoll.new
+    #  => #<Kernel::Epoll:0x89bca3c @fds={}, @epfd=5>
+    #  irb(main):004:0> ep.add(:socket, r, :events => [:read])
+    #  => true
+    #  irb(main):005:0> ep.poll
+    #  => []
+    #  irb(main):006:0> w.write 'foo'
+    #  => 3
+    #  irb(main):007:0> ep.poll
+    #  => [{:target=>#<IO:0x89be38c>, :event=>:read, :type=>:socket}]
+    #  irb(main):008:0> [r, w, ep].each{|x| x.close }
+    def add_socket(target, options={})
+      fdnum = target.respond_to?(:fileno) ? target.fileno : target
+      events = (options[:events] + (options[:flags] || [])).inject(0){|m,i| m | EP_FLAGS[i]}
+
+      ev = Epoll_event.new
+      ev[:events] = events
+      ev[:data] = Epoll_data.new
+      ev[:data][:fd] = fdnum
+
+      if epoll_ctl(@epfd, EPOLL_CTL_ADD, fdnum, ev) == -1
+        return false
+      else
+        @fds[fdnum] = {:target => target, :event => ev}
+        return true
+      end
+    end
+
+    # Poll for an event. Pass an optional timeout float as number of seconds to wait for an event. Default is 0.0 (do not wait).
+    #
+    # Using a timeout will block for the duration of the timeout. Under Ruby 1.9.1, we use rb_thread_blocking_region() under the
+    # hood to allow other threads to run during this call. Prior to 1.9 though, we do not have native threads and hence this call
+    # will block the whole interpreter (all threads) until it returns.
+    #
+    # This call returns an array of hashes, similar to the following:
+    #  => [{:type=>:socket, :target=>#<IO:0x4fa90c>, :event=>:read}]
+    #
+    # * :type - will be the type of event target, i.e. an event set with #add_socket will have :type => :socket
+    # * :target - the 'target' or 'subject' of the event. This can be a File, IO, process or signal number.
+    # * :event - the event that occurred on the target. This is one of the symbols you passed as :events => [:foo] when adding the event.
+    #
+    # Note: even though epoll only supports :socket style descriptors, we keep :type for consistency with other APIs.
+    def poll(timeout=0.0)
+      timeout = (timeout * 1000).to_i
+      ev = Epoll_event.new
+      case epoll_wait(@epfd, ev, 1, timeout)
+      when -1
+        [errno]
+      when 0
+        []
+      else
+        [process_event(ev)]
+      end
+    end
+
+    def process_event(ev) #:nodoc:
+      h = @fds[ev[:data][:fd]]
+      return nil if h.nil?
+
+      event = if ev[:events] & EPOLLIN == EPOLLIN
+        :read
+      elsif ev[:events] & EPOLLOUT == EPOLLOUT
+        :write
+      elsif ev[:events] & ERPOLLPRI == EPOLLPRI
+        :priority
+      elsif ev[:events] & EPOLLERR == EPOLLERR
+        :error
+      elsif ev[:events] & EPOLLHUP == EPOLLHUP
+        :hangup
+      elsif Epoll.const_defined?("EPOLLRDHUP") and ev[:events] & EPOLLRDHUP == EPOLLRDHUP
+        :remote_hangup
+      end
+
+      delete(:socket, h[:target]) if ev[:events] & EPOLLONESHOT == EPOLLONESHOT
+      {:target => h[:target], :event => event, :type => :socket}
+    end
+
+    # Stop generating events for the given type and event target, ie:
+    #  ep.delete(:socket, sock)
+    #
+    # Note: even though epoll only supports :socket style descriptors, we keep this for consistency with other APIs.
+    def delete(type, target)
+      ident = target.respond_to?(:fileno) ? target.fileno : target
+      h = @fds[ident]
+      return false if h.nil?
+      epoll_ctl(@epfd, EPOLL_CTL_DEL, ident, h[:event])
+      return true
+    end
+
+    def close
+      IO.for_fd(@epfd).close
+    end
+
+  end
+end

data/lib/ktools/kqueue.rb

@@ -0,0 +1,388 @@
+module Kernel
+
+  class Kqueue
+    extend FFI::Library
+
+    class Kevent < FFI::Struct
+      layout :ident, :uint, 
+      :filter, :short, 
+      :flags, :ushort, 
+      :fflags, :uint, 
+      :data, :int, 
+      :udata, :pointer
+    end
+
+    class Timespec < FFI::Struct
+      layout :tv_sec, :long,
+        :tv_nsec, :long
+    end
+
+    kqc = FFI::ConstGenerator.new do |c|
+      c.include 'sys/event.h'
+
+      # filters - signed short
+      c.const("EVFILT_READ", "%d")
+      c.const("EVFILT_WRITE", "%d")
+      c.const("EVFILT_AIO", "%d")
+      c.const("EVFILT_VNODE", "%d")
+      c.const("EVFILT_PROC", "%d")
+      c.const("EVFILT_SIGNAL", "%d")
+
+      # flags - unsigned short
+      c.const("EV_ADD", "%u")
+      c.const("EV_DELETE", "%u")
+      c.const("EV_ENABLE", "%u")
+      c.const("EV_DISABLE", "%u")
+      c.const("EV_RECEIPT", "%u")
+      c.const("EV_ONESHOT", "%u")
+      c.const("EV_CLEAR", "%u")
+      c.const("EV_SYSFLAGS", "%u")
+      c.const("EV_FLAG0", "%u")
+      c.const("EV_FLAG1", "%u")
+      c.const("EV_EOF", "%u")
+      c.const("EV_ERROR", "%u")
+      c.const("EV_POLL", "%u")
+      c.const("EV_OOBAND", "%u")
+
+      # fflags - unsigned int
+      c.const("NOTE_LOWAT", "%u")
+      c.const("NOTE_DELETE", "%u")
+      c.const("NOTE_WRITE", "%u")
+      c.const("NOTE_EXTEND", "%u")
+      c.const("NOTE_ATTRIB", "%u")
+      c.const("NOTE_LINK", "%u")
+      c.const("NOTE_RENAME", "%u")
+      c.const("NOTE_REVOKE", "%u")
+      c.const("NOTE_EXIT", "%u")
+      c.const("NOTE_FORK", "%u")
+      c.const("NOTE_EXEC", "%u")
+      c.const("NOTE_REAP", "%u")
+      c.const("NOTE_SIGNAL", "%u")
+      c.const("NOTE_PDATAMASK", "%u")
+      c.const("NOTE_PCTRLMASK", "%u")
+      c.const("NOTE_SECONDS", "%u")
+      c.const("NOTE_USECONDS", "%u")
+      c.const("NOTE_NSECONDS", "%u")
+      c.const("NOTE_ABSOLUTE", "%u")
+      c.const("NOTE_TRACK", "%u")
+      c.const("NOTE_TRACKERR", "%u")
+      c.const("NOTE_CHILD", "%u")
+    end
+
+    eval kqc.to_ruby
+
+    KQ_FILTERS = {
+      :read => EVFILT_READ,
+      :write => EVFILT_WRITE,
+      :file => EVFILT_VNODE,
+      :process => EVFILT_PROC,
+      :signal => EVFILT_SIGNAL
+    }
+
+    KQ_FLAGS = {
+      :add => EV_ADD,
+      :enable => EV_ENABLE,
+      :disable => EV_DISABLE,
+      :delete => EV_DELETE,
+      :oneshot => EV_ONESHOT,
+      :clear => EV_CLEAR
+    }
+
+    KQ_FFLAGS = {
+      :delete => NOTE_DELETE,
+      :write => NOTE_WRITE,
+      :extend => NOTE_EXTEND,
+      :attrib => NOTE_ATTRIB,
+      :link => NOTE_LINK,
+      :rename => NOTE_RENAME,
+      :revoke => NOTE_REVOKE,
+      :exit => NOTE_EXIT,
+      :fork => NOTE_FORK,
+      :exec => NOTE_EXEC
+    }
+
+    # Leopard has these, Tiger does not.
+    KQ_FLAGS[:receipt] = EV_RECEIPT if const_defined?("EV_RECEIPT")
+    KQ_FFLAGS[:signal] = NOTE_SIGNAL if const_defined?("NOTE_SIGNAL")
+    KQ_FFLAGS[:reap] = NOTE_REAP if const_defined?("NOTE_REAP")
+
+    # Had to write a wrapper for EV_SET since its a macro
+    attach_function :ev_set, :wrap_evset, [:pointer, :uint, :short, :ushort, :uint, :int, :pointer], :void
+    # Attach directly to kqueue function, no wrapper needed
+    attach_function :kqueue, [], :int
+    # We wrap kqueue and kevent because we use rb_thread_blocking_region when it's available in MRI
+    attach_function :kevent, :wrap_kevent, [:int, :pointer, :int, :pointer, :int, Timespec], :int
+
+    # We provide the raw C interface above. Now we OO-ify it.
+
+    # Creates a new kqueue event queue. Will raise an error if the operation fails.
+    def initialize
+      @fds = {}
+      @pids = {}
+      @kqfd = kqueue
+      raise SystemCallError.new("Error creating kqueue descriptor", get_errno) unless @kqfd > 0
+    end
+
+    # Generic method for adding events. This simply calls the proper add_foo method specified by the type symbol.
+    # Example:
+    #  kq.add(:process, pid, :events => [:fork])
+    #  calls -> kq.add_process(pid, events => [:fork])
+    def add(type, target, options={})
+      case type
+      when :socket
+        add_socket(target, options)
+      when :file
+        add_file(target, options)
+      when :process
+        add_process(target, options)
+      when :signal
+        add_signal(target, options)
+      else
+        raise ArgumentError.new("Unknown event type #{type}")
+      end
+    end
+
+    # Add events on a file to the Kqueue. kqueue requires that a file actually be opened (to get a descriptor)
+    # before it can be monitored. You can pass a File object here, or a String of the pathname, in which
+    # case we'll try to open the file for you. In either case, a File object will be returned as the :target 
+    # in the event returned by #poll. If you want to keep track of it yourself, you can just pass the file
+    # descriptor number (and that's what you'll get back.)
+    #
+    # Valid events here are as follows, using descriptions from the kqueue man pages:
+    #
+    # * :delete - "The unlink() system call was called on the file referenced by the descriptor."
+    # * :write  - "A write occurred on the file referenced by the descriptor."
+    # * :extend - "The file referenced by the descriptor was extended."
+    # * :attrib - "The file referenced by the descriptor had its attributes changed."
+    # * :link   - "The link count on the file changed."
+    # * :rename - "The file referenced by the descriptor was renamed."
+    # * :revoke - "Access to the file was revoked via revoke(2) or the underlying fileystem was unmounted."
+    #
+    # Example:
+    #  irb(main):001:0> require 'ktools'
+    #  => true
+    #  irb(main):002:0> file = Tempfile.new("kqueue-test")
+    #  => #<File:/tmp/kqueue-test20090417-602-evm5wc-0>
+    #  irb(main):003:0> kq = Kqueue.new
+    #  => #<Kernel::Kqueue:0x4f0aec @kqfd=5, @fds={}>
+    #  irb(main):004:0> kq.add(:file, file, :events => [:write, :delete])
+    #  => true
+    #  irb(main):005:0> kq.poll
+    #  => []
+    #  irb(main):006:0> file.delete
+    #  => #<File:/tmp/kqueue-test20090417-602-evm5wc-0>
+    #  irb(main):007:0> kq.poll
+    #  => [{:type=>:file, :target=>#<File:/tmp/kqueue-test20090417-602-evm5wc-0>, :event=>:delete}]
+    #  irb(main):008:0> file.close and kq.close 
+    #  => nil
+    def add_file(file, options={})
+      fflags, flags = options.values_at :events, :flags
+      raise ArgumentError.new("must specify which file events to watch for") unless fflags
+
+      file = file.kind_of?(String) ? File.open(file, 'r') : file
+      fdnum = file.respond_to?(:fileno) ? file.fileno : file
+
+      k = Kevent.new
+      flags = flags ? flags.inject(0){|m,i| m | KQ_FLAGS[i] } : EV_CLEAR
+      fflags = fflags.inject(0){|m,i| m | KQ_FFLAGS[i] }
+      ev_set(k, fdnum, EVFILT_VNODE, EV_ADD | flags, fflags, 0, nil)
+
+      if kevent(@kqfd, k, 1, nil, 0, nil) == -1
+        return false
+      else
+        @fds[fdnum] = {:target => file, :event => k}
+        return true
+      end
+    end
+
+    # Add events to a socket-style descriptor (socket or pipe). Your target can be either
+    # an IO object (socket, pipe), or a file descriptor number.
+    #
+    # Supported events are:
+    #
+    # * :read - The descriptor has become readable.
+    # * :write - The descriptor has become writeable.
+    #
+    # See the kqueue manpage for how behavior differs depending on the descriptor types. 
+    # In general, you shouldn't have to worry about it.
+    #
+    # Example:
+    #  irb(main):001:0> require 'ktools'
+    #  => true
+    #  irb(main):002:0> r, w = IO.pipe
+    #  => [#<IO:0x4fa90c>, #<IO:0x4fa880>]
+    #  irb(main):003:0> kq = Kqueue.new
+    #  => #<Kernel::Kqueue:0x4f43a4 @kqfd=6, @fds={}>
+    #  irb(main):004:0> kq.add(:socket, r, :events => [:read, :write])
+    #  => true
+    #  irb(main):005:0> kq.poll
+    #  => []
+    #  irb(main):006:0> w.write "foo"
+    #  => 3
+    #  irb(main):007:0> kq.poll
+    #  => [{:type=>:socket, :target=>#<IO:0x4fa90c>, :event=>:read}]
+    #  irb(main):008:0> [r, w, kq].each {|i| i.close}
+    def add_socket(target, options={})
+      filters, flags = options.values_at :events, :flags
+      flags = flags ? flags.inject(0){|m,i| m | KQ_FLAGS[i] } : EV_CLEAR
+      filters = filters ? filters.inject(0){|m,i| m | KQ_FILTERS[i] } : EVFILT_READ | EVFILT_WRITE
+      fdnum = target.respond_to?(:fileno) ? target.fileno : target
+
+      k = Kevent.new
+      ev_set(k, fdnum, filters, EV_ADD | flags, 0, 0, nil)
+
+      if kevent(@kqfd, k, 1, nil, 0, nil) == -1
+        return false
+      else
+        @fds[fdnum] = {:target => target, :event => k}
+        return true
+      end
+    end
+
+    # Add events for a process. Takes a process id and and options hash. Supported events are:
+    # * :exit - The process has exited
+    # * :fork - The process has created a child process via fork(2) or similar call.
+    # * :exec - The process executed a new process via execve(2) or similar call.
+    # * :signal - The process was sent a signal. Status can be checked via waitpid(2) or similar call.
+    # * :reap - The process was reaped by the parent via wait(2) or similar call.\
+    #
+    # Note: SIGNAL and REAP do not appear to exist in OSX older than Leopard.
+    #
+    # Example:
+    #  irb(main):001:0> require 'ktools'
+    #  => true
+    #  irb(main):002:0> kq = Kqueue.new
+    #  => #<Kernel::Kqueue:0x14f55b4 @kqfd=4, @pids={}, @fds={}>
+    #  irb(main):003:0> fpid = fork{ sleep } 
+    #  => 616
+    #  irb(main):004:0> kq.add(:process, fpid, :events => [:exit])
+    #  => true
+    #  irb(main):005:0> Process.kill('TERM', fpid)
+    #  => 1
+    #  irb(main):006:0> kq.poll.first
+    #  => {:event=>:exit, :type=>:process, :target=>616}
+    #
+    def add_process(pid, options={})
+      flags, fflags = options.values_at :flags, :events
+      flags = flags ? flags.inject(0){|m,i| m | KQ_FLAGS[i] } : EV_CLEAR
+      fflags = fflags.inject(0){|m,i| m | KQ_FFLAGS[i] }
+
+      k = Kevent.new
+      ev_set(k, pid, EVFILT_PROC, EV_ADD | flags, fflags, 0, nil)
+
+      if kevent(@kqfd, k, 1, nil, 0, nil) == -1
+        return false
+      else
+        @pids[pid] = {:target => pid, :event => k}
+        return true
+      end
+    end
+
+    # Poll for an event. Pass an optional timeout float as number of seconds to wait for an event. Default is 0.0 (do not wait).
+    #
+    # Using a timeout will block for the duration of the timeout. Under Ruby 1.9.1, we use rb_thread_blocking_region() under the
+    # hood to allow other threads to run during this call. Prior to 1.9 though, we do not have native threads and hence this call
+    # will block the whole interpreter (all threads) until it returns.
+    #
+    # This call returns an array of hashes, similar to the following:
+    #  => [{:type=>:socket, :target=>#<IO:0x4fa90c>, :event=>:read}]
+    #
+    # * :type - will be the type of event target, i.e. an event set with #add_file will have :type => :file
+    # * :target - the 'target' or 'subject' of the event. This can be a File, IO, process or signal number.
+    # * :event - the event that occurred on the target. This is one of the symbols you passed as :events => [:foo] when adding the event.
+    def poll(timeout=0.0)
+      k = Kevent.new
+      t = Timespec.new
+      t[:tv_sec] = timeout.to_i
+      t[:tv_nsec] = ((timeout - timeout.to_i) * 1e9).to_i
+
+      case kevent(@kqfd, nil, 0, k, 1, t)
+      when -1
+        [errno]
+      when 0
+        []
+      else
+        [process_event(k)]
+      end
+    end
+
+    def process_event(k) #:nodoc:
+      res = case k[:filter]
+      when EVFILT_VNODE
+        h = @fds[k[:ident]]
+        return nil if h.nil?
+        event = if k[:fflags] & NOTE_DELETE == NOTE_DELETE
+          :delete
+        elsif k[:fflags] & NOTE_WRITE == NOTE_WRITE
+          :write
+        elsif k[:fflags] & NOTE_EXTEND == NOTE_EXTEND
+          :extend
+        elsif k[:fflags] & NOTE_ATTRIB == NOTE_ATTRIB
+          :attrib
+        elsif k[:fflags] & NOTE_LINK == NOTE_LINK
+          :link
+        elsif k[:fflags] & NOTE_RENAME == NOTE_RENAME
+          :rename
+        elsif k[:fflags] & NOTE_REVOKE == NOTE_REVOKE
+          :revoke
+        end
+        delete(:file, k[:ident]) if event == :delete || event == :revoke
+        {:target => h[:target], :type => :file, :event => event}
+      when EVFILT_READ
+        h = @fds[k[:ident]]
+        return nil if h.nil?
+        {:target => h[:target], :type => :socket, :event => :read}
+      when EVFILT_WRITE
+        h = @fds[k[:ident]]
+        return nil if h.nil?
+        {:target => h[:target], :type => :socket, :event => :write}
+      when EVFILT_PROC
+        h = @pids[k[:ident]]
+        return nil if h.nil?
+        event = if k[:fflags] & NOTE_EXIT == NOTE_EXIT
+          :exit
+        elsif k[:fflags] & NOTE_FORK == NOTE_FORK
+          :fork
+        elsif k[:fflags] & NOTE_EXEC == NOTE_EXEC
+          :exec
+        elsif Kqueue.const_defined?("NOTE_SIGNAL") and k[:fflags] & NOTE_SIGNAL == NOTE_SIGNAL
+          :signal
+        elsif Kqueue.const_defined?("NOTE_REAP") and k[:fflags] & NOTE_REAP == NOTE_REAP
+          :reap
+        end
+        delete(:process, k[:ident]) if event == :exit
+        {:target => h[:target], :type => :process, :event => event}
+      end
+
+      delete(res[:type], res[:target]) if k[:flags] & EV_ONESHOT == EV_ONESHOT
+      res
+    end
+
+    # Stop generating events for the given type and event target, ie:
+    #  kq.delete(:process, 6244)
+    def delete(type, target)
+      ident = target.respond_to?(:fileno) ? target.fileno : target
+      container = case type
+      when :socket
+        @fds
+      when :file
+        @fds
+      when :process
+        @pids
+      end
+      h = container[ident]
+      return false if h.nil?
+      k = h[:event]
+      ev_set(k, k[:ident], k[:filter], EV_DELETE, k[:fflags], 0, nil)
+      kevent(@kqfd, k, 1, nil, 0, nil)
+      container.delete(ident)
+      return true
+    end
+
+    # Close the kqueue descriptor. This essentially shuts down your kqueue and renders all active events on this kqueue removed. 
+    def close
+      IO.for_fd(@kqfd).close
+    end
+
+  end
+end

data/lib/ktools/ktools.rb

@@ -0,0 +1,18 @@
+module Kernel
+  extend FFI::Library
+  ffi_lib Dir.glob(File.dirname(File.expand_path(__FILE__)) + "/../ktools.*").select{|x| x =~ /\.so$/ || x =~ /\.bundle$/}.first
+
+  # Tells us from Ruby whether or not we have built with support for these libraries
+  %w[epoll kqueue inotify netlink].each do |m|
+    attach_function "have_#{m}".to_sym, [], :int
+    define_method("have_#{m}?") { (self.send "have_#{m}") > 0 ? true : false }
+  end
+
+  attach_function :get_errno, [], :int
+
+  # Returns the current system errno as a Ruby Errno object
+  def errno
+    SystemCallError.new(get_errno)
+  end
+
+end

data/lib/ktools.rb

@@ -0,0 +1,6 @@
+$:.unshift File.expand_path(File.dirname(File.expand_path(__FILE__)))
+require 'ffi'
+require 'ffi/tools/const_generator'
+require 'ktools/ktools'
+require 'ktools/kqueue' if Kernel.have_kqueue?
+require 'ktools/epoll' if Kernel.have_epoll?

data/tests/test_epoll.rb

@@ -0,0 +1,69 @@
+describe "the epoll interface" do
+
+  it "should return a valid epoll file descriptor" do
+    @epfd = Epoll::epoll_create(10)
+    @epfd.class.should.equal Fixnum
+    @epfd.should.be > 0
+  end
+
+  it "should set an event for readable status of a descriptor, and retrieve the event when it occurs" do
+    r, w = IO.pipe
+    ev = Epoll::Epoll_event.new
+    ev[:events] = Epoll::EPOLLIN
+    ev[:data] = Epoll::Epoll_data.new
+    ev[:data][:fd] = r.fileno
+    ev[:data][:u32] = 12345
+    Epoll::epoll_ctl(@epfd, Epoll::EPOLL_CTL_ADD, r.fileno, ev).should.equal 0
+    rev = Epoll::Epoll_event.new
+    Epoll::epoll_wait(@epfd, rev, 1, 50).should.equal 0
+    w.write "foo"
+    Epoll::epoll_wait(@epfd, rev, 1, 50).should.equal 1
+    rev[:events].should.equal Epoll::EPOLLIN
+    rev[:data][:fd].should.equal r.fileno
+    rev[:data][:u32].should.equal 12345
+    w.close
+    r.close
+    w.should.be.closed
+    r.should.be.closed
+  end
+
+  it "should close the epoll file descriptor" do
+    i = IO.for_fd(@epfd)
+    i.should.not.be.closed
+    i.close
+    i.should.be.closed
+  end
+
+  it "should add socket events and retrieve them using the Ruby API" do
+    r, w = IO.pipe
+    ep = Epoll.new
+
+    ep.add(:socket, r, :events => [:read]).should.be.true
+    ep.poll.should.be.empty
+
+    w.write 'foo'
+    res = ep.poll.first
+
+    res[:event].should.equal :read
+    res[:target].fileno.should.equal r.fileno
+    res[:type].should.equal :socket
+
+    [r,w,ep].each{|i| i.close}
+  end
+
+  it "should delete events using the Ruby API" do
+    r, w = IO.pipe
+    ep = Epoll.new
+
+    ep.add(:socket, r, :events => [:read]).should.be.true
+    ep.poll.should.be.empty
+
+    w.write 'foo'
+    ep.delete(:socket, r).should.be.true
+
+    ep.poll.should.be.empty
+
+    [r,w,ep].each{|i| i.close}
+  end
+
+end

data/tests/test_kqueue.rb

@@ -0,0 +1,109 @@
+describe "the kqueue interface" do
+
+  it "should return a valid kqueue file descriptor" do
+    @kqfd = Kqueue::kqueue
+    @kqfd.class.should.equal Fixnum
+    @kqfd.should.be > 0
+  end
+
+  it "should use the raw C API to set an event for file watching, and retrieve the event when it occurs" do
+    file = Tempfile.new("kqueue-test")
+    k = Kqueue::Kevent.new
+    k.should.not.be.nil
+    Kqueue::ev_set(k, file.fileno, Kqueue::EVFILT_VNODE, Kqueue::EV_ADD | Kqueue::EV_CLEAR, Kqueue::NOTE_WRITE, 0, nil)
+    Kqueue::kevent(@kqfd, k, 1, nil, 0, nil)
+    File.open(file.path, 'w'){|x| x.puts 'foo'}
+    n = Kqueue::Kevent.new
+    res = Kqueue::kevent(@kqfd, nil, 0, n, 1, nil)
+    res.should.be > -1
+    n[:ident].should.equal file.fileno
+    n[:filter].should.equal Kqueue::EVFILT_VNODE
+    n[:fflags].should.equal Kqueue::NOTE_WRITE
+    file.close
+  end
+
+  it "should close the kqueue file descriptor" do
+    i = IO.for_fd(@kqfd)
+    i.should.not.be.closed
+    i.close
+    i.should.be.closed
+  end
+
+  it "should add file events using the ruby API" do
+    file = Tempfile.new("kqueue-test")
+    kq = Kqueue.new
+    kq.add(:file, file, :events => [:write, :delete]).should.be.true
+
+    kq.poll.should.be.empty
+    File.open(file.path, 'w'){|x| x.puts 'foo'}
+
+    res = kq.poll.first
+    res.class.should.equal Hash
+    res[:target].class.should.equal Tempfile
+    res[:target].fileno.should.equal file.fileno
+    res[:type].should.equal :file
+    res[:event].should.equal :write
+
+    kq.poll.should.be.empty
+    file.delete
+
+    res2 = kq.poll.first
+    res2[:target].class.should.equal Tempfile
+    res2[:target].fileno.should.equal file.fileno
+    res2[:type].should.equal :file
+    res2[:event].should.equal :delete
+
+    file.close
+    kq.close
+  end
+
+  it "should add events for socket-style descriptors, then delete them, using the Ruby API" do
+    r, w = IO.pipe
+    kq = Kqueue.new
+    kq.add(:socket, r, :events => [:read]).should.be.true
+
+    kq.poll.should.be.empty
+    w.write "foo"
+
+    res = kq.poll.first
+    res[:target].class.should.equal IO
+    res[:target].fileno.should.equal r.fileno
+    res[:type].should.equal :socket
+    res[:event].should.equal :read
+
+    kq.poll.should.be.empty
+    kq.delete(:socket, r).should.be.true
+    w.write "foo"
+    kq.poll.should.be.empty
+
+    [r,w,kq].each{|i| i.close}
+  end
+
+  it "should add events for a process using the Ruby API" do
+    kq = Kqueue.new
+    # Watch for ourself to fork
+    kq.add(:process, Process.pid, :events => [:fork]).should.be.true
+
+    fpid = fork{ at_exit {exit!}; sleep }
+
+    res = kq.poll(1).first
+    res[:target].should.equal Process.pid
+    res[:type].should.equal :process
+    res[:event].should.equal :fork
+
+    # Watch for the child to exit and kill it
+    kq.add(:process, fpid, :events => [:exit])
+    sleep 0.5
+    Process.kill('TERM', fpid)
+
+    res2 = kq.poll(1).first
+    res2[:target].should.equal fpid
+    res2[:type].should.equal :process
+    res2[:event].should.equal :exit
+
+    kq.poll.should.be.empty
+
+    kq.close
+  end
+
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: yakischloba-ktools
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Jake Douglas
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-22 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: ffi
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: bacon
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Bringing common kernel APIs into Ruby using FFI
+email: jakecdouglas@gmail.com
+executables: []
+
+extensions: 
+- Rakefile
+extra_rdoc_files: []
+
+files: 
+- ktools.gemspec
+- README
+- Rakefile
+- lib/ktools.rb
+- lib/ktools/ktools.rb
+- lib/ktools/epoll.rb
+- lib/ktools/kqueue.rb
+- ext/ktools.c
+- ext/ktools.h
+- ext/epoll.c
+- ext/epoll.h
+- ext/kqueue.c
+- ext/kqueue.h
+- tests/test_epoll.rb
+- tests/test_kqueue.rb
+has_rdoc: true
+homepage: http://www.github.com/yakischloba/ktools
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: ktools
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Bringing common kernel APIs into Ruby using FFI
+test_files: []
+