ktools 0.0.1 → 0.0.2

data/README

@@ -23,13 +23,14 @@ Synopsis:
 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.)
+epoll (works - see tests/test_epoll.rb)
 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.
+as possible, and then write Rubyist-friendly wrappers around them.
+
+Currently kqueue and epoll have Ruby wrapper APIs.
 
 
 To install:

data/Rakefile

@@ -57,9 +57,12 @@ task :clean do
 end
 
 task :test do
+  require 'rubygems'
   require 'lib/ktools'
-  sh "bacon tests/test_kqueue.rb" if Kernel.have_kqueue?
-  sh "bacon tests/test_epoll.rb" if Kernel.have_epoll?
+  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

data/ktools.gemspec

@@ -1,12 +1,13 @@
 Gem::Specification.new do |s|
   s.name = "ktools"
-  s.version = "0.0.1"
-  s.date = "2009-04-21"
+  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"

data/lib/ktools/epoll.rb

@@ -1,5 +1,5 @@
 module Kernel
-  module Epoll
+  class Epoll
     extend FFI::Library
 
     class Epoll_data < FFI::Struct
@@ -11,7 +11,11 @@ module Kernel
 
     class Epoll_event < FFI::Struct
       layout :events, :uint32,
-        :data, Epoll_data
+        :data, :pointer
+
+      def [] key
+        key == :data ? Epoll_data.new(super(key)) : super(key)
+      end
     end
 
     epc = FFI::ConstGenerator.new do |c|
@@ -26,6 +30,7 @@ module Kernel
       c.const("EPOLLMSG")
       c.const("EPOLLERR")
       c.const("EPOLLHUP")
+      c.const("EPOLLRDHUP")
       c.const("EPOLLONESHOT")
       c.const("EPOLLET")
       c.const("EPOLL_CTL_ADD")
@@ -35,11 +40,164 @@ module Kernel
 
     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

@@ -115,7 +115,7 @@ module Kernel
 
     # We provide the raw C interface above. Now we OO-ify it.
 
-    # Creates a new kqueue object. Will raise an error if the operation fails.
+    # Creates a new kqueue event queue. Will raise an error if the operation fails.
     def initialize
       @fds = {}
       @pids = {}
@@ -137,13 +137,18 @@ module Kernel
         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. Valid events here are as follows, using descriptions from the kqueue man pages:
+    # 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."
@@ -174,22 +179,26 @@ module Kernel
       fflags, flags = options.values_at :events, :flags
       raise ArgumentError.new("must specify which file events to watch for") unless fflags
 
-      file = file.kind_of?(File) || file.kind_of?(Tempfile) ? file : File.open(file, 'r')
+      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, file.fileno, EVFILT_VNODE, EV_ADD | flags, fflags, 0, nil)
+      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[file.fileno] = {:target => file, :kevent => k}
+        @fds[fdnum] = {:target => file, :event => k}
         return true
       end
     end
 
-    # Add events to a socket-style descriptor (socket or pipe). Supported events are:
+    # 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.
@@ -213,18 +222,19 @@ module Kernel
     #  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(io, options={})
+    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, io.fileno, filters, EV_ADD | flags, 0, 0, nil)
+      ev_set(k, fdnum, filters, EV_ADD | flags, 0, 0, nil)
 
       if kevent(@kqfd, k, 1, nil, 0, nil) == -1
         return false
       else
-        @fds[io.fileno] = {:target => io, :kevent => k}
+        @fds[fdnum] = {:target => target, :event => k}
         return true
       end
     end
@@ -263,7 +273,7 @@ module Kernel
       if kevent(@kqfd, k, 1, nil, 0, nil) == -1
         return false
       else
-        @pids[pid] = {:target => pid, :kevent => k}
+        @pids[pid] = {:target => pid, :event => k}
         return true
       end
     end
@@ -362,7 +372,7 @@ module Kernel
       end
       h = container[ident]
       return false if h.nil?
-      k = h[:kevent]
+      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)

data/tests/test_epoll.rb

@@ -1,29 +1,24 @@
-require 'lib/ktools'
-require 'bacon'
-
-include Kernel::Epoll
-
 describe "the epoll interface" do
 
   it "should return a valid epoll file descriptor" do
-    @epfd = epoll_create(10)
+    @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_event.new
-    ev[:events] = EPOLLIN
-    ev[:data] = Epoll_data.new
+    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_ctl(@epfd, EPOLL_CTL_ADD, r.fileno, ev).should.equal 0
-    rev = Epoll_event.new
-    epoll_wait(@epfd, rev, 1, 50).should.equal 0
+    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_wait(@epfd, rev, 1, 50).should.equal 1
-    rev[:events].should.equal EPOLLIN
+    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
@@ -39,4 +34,36 @@ describe "the epoll interface" do
     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

@@ -1,6 +1,3 @@
-require 'lib/ktools'
-require 'bacon'
-
 describe "the kqueue interface" do
 
   it "should return a valid kqueue file descriptor" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ktools
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Jake Douglas
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-21 00:00:00 -07:00
+date: 2009-04-22 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -22,6 +22,16 @@ dependencies:
       - !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: []