bran 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 36a615f86cbc15a2b7c138816df60678ca2a0786
+  data.tar.gz: 48570f692b614243db475256f19265f74993be70
+SHA512:
+  metadata.gz: c14a66422d3310bc2619afb7c59e883c6c9ec6022b7e9139b7800b2a5aa3ca1114cab48ce76d4bce553ffbcab647de60c5604dfbc8f4f6159649ea3a18c31e6e
+  data.tar.gz: 2ba3d09c4a6786b300e3c4c96030ed692fdc60a880c539a396efc42ba081eb66c190529e4c9bc217d12fd415399b1bacc1088b9fe5b0261f6f616fcb17ab21e8

data/README.md

@@ -0,0 +1,43 @@
+# Bran
+
+## Integrations
+
+Bran is most useful when integrated with every part of your application that performs I/O. Because I/O is commonly abstracted away from our applications by libraries, Bran includes integrations and patches for various third-party libraries so that they can use Bran to yield control to other Fibers while waiting for I/O.
+
+It's important to realize that some of these integrations may depend on "implementation details" of the libraries that they patch. Some libraries do not expose the public interfaces we need to integrate Bran with their I/O path, and some libraries do not even make it _clear_ which interfaces are public API and which interfaces are implementation details.
+
+Bran integrations try to use only public interfaces wherever possible, and will otherwise try to make explicit assumptions about the interfaces they expect. Some of these assumptions can be checked at runtime when loading the integrations (attempt to "fail eagerly" in the case of poor integration). To enable this behavior, do the following before loading any Bran integration:
+
+```ruby
+require "bran/ext"
+
+Bran::Ext.check_assumptions = true
+
+# Load specific Bran integrations here.
+```
+
+The description of each Bran integration will also be labeled "Tested with" for known good combinations of dependent gems.
+
+### Rainbows
+
+Use Bran with [Rainbows][rainbows], a [Unicorn][unicorn]-based and [Unicorn][unicorn]-compatible webserver from the creators of [Unicorn][unicorn].
+
+Each worker process will allow multiple concurrent connections, accepted by the Bran adapter into a fixed-size fiber pool, with the fibers being managed by Bran. Without any other Bran integrations, you can expect this configuration to only process one request at a time, with performance on par with that of Unicorn. Using other Bran I/O integrations while handling requests will give the fibers a chance to work concurrently, increasing performance for I/O-bound loads.
+
+To activate the Bran integration, try adding the following example configuration to your Unicorn/Rainbows config file (often called `unicorn.rb`):
+
+```ruby
+require "bran/ext/rainbows"
+
+Rainbows! do
+  use :Bran              # use the Bran adapter as the concurrency manager
+  worker_connections 100 # accept 100 connections per worker (100 fibers)
+end
+```
+
+Tested with:
+- `rainbows 5.0.0` (`unicorn 5.0.0`, `kgio 2.10.0`)
+- `rainbows 5.0.0` (`unicorn 5.0.1`, `kgio 2.10.0`)
+
+[rainbows]: http://rainbows.bogomips.org/
+[unicorn]:  http://unicorn.bogomips.org/

data/ext/libuv/Rakefile

@@ -0,0 +1,93 @@
+
+require "rake/clean"
+require "ffi"
+
+FILES = {}
+
+task :default => [:build, :compact]
+
+def self.file_task(filename, opts, &block)
+  name, dep = opts.is_a?(Hash) ? opts.to_a.first : [opts, nil]
+  
+  FILES[name] = filename
+  CLEAN.include filename
+  task name => filename
+  
+  if dep
+    file filename => FILES[dep], &block
+  else
+    file filename, &block
+  end
+end
+
+def cmd(string)
+  fail "Command failed: #{string}" unless system(string)
+end
+
+file_task "libuv.tar.gz", :download_tarball do
+  version = "1.8.0"
+  release = "https://github.com/libuv/libuv/archive/v#{version}.tar.gz"
+  cmd "wget -O #{FILES[:download_tarball]} #{release}"
+end
+
+file_task "libuv", :download => :download_tarball do
+  cmd "tar -zxf #{FILES[:download_tarball]}"
+  cmd "mv libuv-* #{FILES[:download]}"
+end
+
+file_task "autogen.touch", :autogen => :download do
+  cmd "/usr/bin/env sh -c 'cd #{FILES[:download]} && ./autogen.sh'"
+  cmd "touch #{FILES[:autogen]}"
+end
+
+file_task "configure.touch", :configure => :autogen do
+  cmd "/usr/bin/env sh -c 'cd #{FILES[:download]} && ./configure'"
+  cmd "touch #{FILES[:configure]}"
+end
+
+# TODO: try to get patch accepted upstream?
+file_task "patch.touch", :patch => :configure do
+  uv_header = "#{FILES[:download]}/include/uv.h"
+  uv_source = "#{FILES[:download]}/src/uv-common.c"
+  
+  ##
+  # Patch 1 - runtime detection for the sizeof each struct type.
+  
+  types     = []
+  not_types = []
+  File.read(uv_header).each_line do |line|
+    # Record the type from each struct typedef.
+    match = /typedef struct uv_\w+_s (uv_\w+?)_t;/.match line
+    types << match[1] if match
+    
+    # Don't record the type if it already has a sizeof function.
+    match = /UV_EXTERN size_t (uv_\w+?)_sizeof\(void\);/.match line
+    not_types << match[1] if match
+  end
+  types -= not_types
+  
+  # Declare the sizeof function for each recorded type.
+  File.open uv_header, "a" do |file|
+    types.each do |type|
+      file.puts("UV_EXTERN size_t #{type}_sizeof(void);")
+    end
+  end
+  
+  # Implement the sizeof function for each recorded type.
+  File.open uv_source, "a" do |file|
+    types.each do |type|
+      file.puts("size_t #{type}_sizeof(void) { return sizeof(#{type}_t); }")
+    end
+  end
+end
+
+file_task "libuv.#{::FFI::Platform::LIBSUFFIX}", :build => :patch do
+  cmd "/usr/bin/env sh -c 'cd #{FILES[:download]} && make'"
+  cmd "cp #{FILES[:download]}/.libs/#{FILES[:build]} ."
+end
+
+task :compact => FILES[:build] do
+  FILES.each do |key, filename|
+    cmd "rm -rf #{filename}" unless key == :build
+  end
+end

data/lib/bran.rb

@@ -0,0 +1,4 @@
+
+require_relative "bran/libuv"
+
+require_relative "bran/fiber_manager"

data/lib/bran/ext.rb

@@ -0,0 +1,35 @@
+
+module Bran
+  class Ext
+    
+    class << self
+      attr_accessor :check_assumptions
+      
+      def assume(&block)
+        return unless @check_assumptions
+        
+        instance_eval &block
+      end
+      
+      def check(cond)
+        return if cond
+        
+        match = caller.first.match(/\A(.+?):(\d+):in/)
+        line  = File.read(match[1]).each_line.to_a[Integer(match[2]) - 1].strip
+        
+        fail "Bran extension compatibility check failed: #{line}"
+      end
+      
+      REGISTRY = {}
+      
+      def []=(ext_name, value)
+        REGISTRY[ext_name] = value
+      end
+      
+      def [](ext_name)
+        REGISTRY[ext_name]
+      end
+    end
+    
+  end
+end

data/lib/bran/ext/io.rb

@@ -0,0 +1,107 @@
+
+require_relative "../../bran"
+require_relative "../../bran/ext"
+
+::Bran::Ext[:io] = true
+
+# TODO: split to io-read.rb
+Module.new do
+  IO.prepend self
+  
+  def getbyte(*)
+    fm = Thread.current.thread_variable_get(:fiber_manager)
+    fm.wait_for_readable!(to_i) if fm
+    super
+  end
+  
+  def getc(*)
+    fm = Thread.current.thread_variable_get(:fiber_manager)
+    fm.wait_for_readable!(to_i) if fm
+    super
+  end
+  
+  def gets(*)
+    fm = Thread.current.thread_variable_get(:fiber_manager)
+    fm.wait_for_readable!(to_i) if fm
+    super
+  end
+  
+  def read(*)
+    fm = Thread.current.thread_variable_get(:fiber_manager)
+    fm.wait_for_readable!(to_i) if fm
+    super
+  end
+  
+  def readbyte(*)
+    fm = Thread.current.thread_variable_get(:fiber_manager)
+    fm.wait_for_readable!(to_i) if fm
+    super
+  end
+  
+  def readchar(*)
+    fm = Thread.current.thread_variable_get(:fiber_manager)
+    fm.wait_for_readable!(to_i) if fm
+    super
+  end
+  
+  def readlines(*)
+    fm = Thread.current.thread_variable_get(:fiber_manager)
+    fm.wait_for_readable!(to_i) if fm
+    super
+  end
+  
+  def readpartial(*)
+    fm = Thread.current.thread_variable_get(:fiber_manager)
+    fm.wait_for_readable!(to_i) if fm
+    super
+  end
+  
+  def sysread(*)
+    fm = Thread.current.thread_variable_get(:fiber_manager)
+    fm.wait_for_readable!(to_i) if fm
+    super
+  end
+end
+
+# TODO: split to io-select.rb
+Module.new do
+  IO.singleton_class.prepend self
+  
+  def select(r_ary = nil, w_ary = nil, e_ary = nil, timeout = nil)
+    fm = Thread.current.thread_variable_get(:fiber_manager)
+    return super unless fm
+    
+    raise NotImplementedError if e_ary && e_ary.any? # TODO: support e_ary?
+    
+    # TODO: move inner implementation to inside FiberManager?
+    fiber  = Fiber.current
+    timer  = nil
+    finish = Proc.new do |item|
+      begin
+        r_ary.each { |io| fm.loop.pop_readable(Integer(io)) } if r_ary
+        w_ary.each { |io| fm.loop.pop_writable(Integer(io)) } if w_ary
+        fm.loop.timer_cancel(timer) if timer
+      ensure
+        fiber.resume(item)
+      end
+    end
+    
+    r_ary.each do |io|
+      fm.loop.push_readable(Integer(io), Proc.new { |*|
+        finish.call([[io], [], []])
+      })
+    end if r_ary
+    
+    w_ary.each do |io|
+      fm.loop.push_writable(Integer(io), Proc.new { |*|
+        finish.call([[], [io], []])
+      })
+    end if w_ary
+    
+    if timeout
+      timer = fm.loop.timer_oneshot(timeout) { timer = nil; finish.call(nil) }
+    end
+    
+    Fiber.yield
+  end
+end

data/lib/bran/ext/rainbows.rb

@@ -0,0 +1,9 @@
+
+require_relative "../../bran"
+require_relative "../../bran/ext"
+
+::Bran::Ext[:rainbows] = true
+
+require "rainbows"
+
+require_relative "rainbows/bran"

data/lib/bran/ext/rainbows/bran.rb

@@ -0,0 +1,64 @@
+
+::Bran::Ext.assume do
+  ::Rainbows::HttpServer.instance_method(:worker_connections).tap do |m|
+    check m.owner == ::Rainbows::HttpServer
+    check m.arity == 0
+  end
+  
+  ::Rainbows::HttpServer.instance_method(:init_worker_process).tap do |m|
+    check m.owner == ::Unicorn::HttpServer
+    check m.arity == 1
+  end
+  
+  ::Rainbows::HttpServer.instance_method(:reopen_worker_logs).tap do |m|
+    check m.owner == ::Unicorn::HttpServer
+    check m.arity == 1
+  end
+  
+  ::Unicorn::HttpServer.instance_method(:process_client).tap do |m|
+    check m.owner == ::Unicorn::HttpServer
+    check m.arity == 1
+  end
+  
+  check ::Unicorn::Worker.instance_method(:nr).arity == 0
+  check ::Kgio::TCPServer.instance_method(:to_i).arity == 0
+end
+
+module Rainbows
+  module Bran
+    include ::Rainbows::Base
+    
+    def worker_loop(worker)
+      readers = init_worker_process(worker)
+      
+      # We have to skip the implementation from Rainbows::Base,
+      # and use the implementation from Unicorn::HttpServer directly.
+      process_client = ::Unicorn::HttpServer.instance_method(:process_client)
+      process_client = process_client.bind(self)
+      
+      manager  = ::Bran::FiberManager.new
+      stopping = false
+      
+      manager.run! do
+        manager.loop.signal_start(:INT)  { exit!(0) }
+        manager.loop.signal_start(:TERM) { exit!(0) }
+        manager.loop.signal_start(:USR1) { reopen_worker_logs(worker.nr) } # TODO: test
+        manager.loop.signal_start(:QUIT) { stopping = true } # TODO: test softness
+        
+        readers.each do |reader|
+          next unless reader.is_a?(::Kgio::TCPServer) # TODO: other readers?
+          
+          worker_connections.times.map do |i|
+            ::Fiber.new do
+              until stopping # TODO: rescue and report errors here
+                manager.wait_for_readable!(reader)
+                process_client.call(reader.kgio_accept)
+              end
+            end.resume
+          end
+        end
+      end
+    end
+    
+  end
+end

data/lib/bran/ext/tcp_server.rb

@@ -0,0 +1,17 @@
+
+require_relative "../../bran"
+require_relative "../../bran/ext"
+
+::Bran::Ext[:tcp_server] = true
+
+require "socket"
+
+Module.new do
+  TCPServer.prepend self
+  
+  def accept(*)
+    fm = Thread.current.thread_variable_get(:fiber_manager)
+    fm.wait_for_readable!(to_i) if fm
+    super
+  end
+end

data/lib/bran/fiber_manager.rb

@@ -0,0 +1,43 @@
+
+require "fiber"
+
+module Bran
+  class FiberManager
+    attr_reader :loop # TODO: hide loop when rest of interface is stable
+    
+    def initialize
+      @loop = LibUV::Reactor.new
+    end
+    
+    def run!
+      Thread.current.thread_variable_set(:fiber_manager, self)
+      
+      yield if block_given?
+      
+      @loop.run!
+    ensure
+      Thread.current.thread_variable_set(:fiber_manager, nil)
+    end
+    
+    def stop!
+      Thread.current.thread_variable_set(:fiber_manager, nil)
+      @loop.stop!
+    end
+    
+    def wait_for_readable!(fd)
+      @loop.push_readable(Integer(fd), ::Fiber.current, false)
+      ::Fiber.yield
+    end
+    
+    def wait_for_writable!(fd)
+      @loop.push_writable(Integer(fd), ::Fiber.current, true)
+      ::Fiber.yield
+    end
+    
+    def wait_for_seconds!(seconds)
+      @loop.timer_oneshot_wake(seconds, ::Fiber.current)
+      ::Fiber.yield
+    end
+    
+  end
+end

data/lib/bran/libuv.rb

@@ -0,0 +1,5 @@
+
+require_relative "libuv/ffi"
+require_relative "libuv/util"
+
+require_relative "libuv/reactor"

data/lib/bran/libuv/ffi.rb

@@ -0,0 +1,103 @@
+
+require "ffi"
+
+module Bran
+  module LibUV
+    module FFI
+      extend ::FFI::Library
+      
+      libfile = "libuv.#{::FFI::Platform::LIBSUFFIX}"
+      
+      ffi_lib \
+        File.expand_path("../../../ext/libuv/#{libfile}", File.dirname(__FILE__))
+      
+      opts = {
+        blocking: true  # only necessary on MRI to deal with the GIL.
+      }
+      
+      UV_READABLE = 1
+      UV_WRITABLE = 2
+      
+      # Struct sizes/allocators
+      %w(uv_loop uv_poll uv_signal uv_timer).each do |type|
+        eval <<-RUBY
+          typedef :pointer, :#{type}_ptr
+          attach_function :#{type}_sizeof, [], :size_t, **opts
+          #{type.upcase}_SIZEOF = #{type}_sizeof
+          
+          def self.#{type}_alloc
+            ptr = ::FFI::MemoryPointer.new(#{type.upcase}_SIZEOF)
+            ptr.autorelease = false
+            ptr
+          end
+        RUBY
+      end
+      
+      typedef :int, :uv_os_sock_t # not true on Windows, but we don't care
+      
+      typedef enum([
+        :default,
+        :once,
+        :nowait
+      ]), :uv_run_mode
+      
+      ##
+      # Callback factory methods.
+      #
+      # WARNING: If your Ruby code doesn't retain a reference to the
+      #   FFI::Function object after passing it to a C function call,
+      #   it may be garbage collected while C still holds the pointer,
+      #   potentially resulting in a segmentation fault.
+      
+      typedef :pointer, :uv_poll_cb_ptr
+      def self.uv_poll_cb(&block)
+        #        (handle,   status, events)
+        params = [:pointer, :int,   :int]
+        ::FFI::Function.new :void, params, blocking: true do |*args|
+          block.call(*args)
+        end
+      end
+      
+      typedef :pointer, :uv_signal_cb_ptr
+      def self.uv_signal_cb(&block)
+        #        (handle,   signo)
+        params = [:pointer, :int]
+        ::FFI::Function.new :void, params, blocking: true do |*args|
+          block.call(*args)
+        end
+      end
+      
+      typedef :pointer, :uv_timer_cb_ptr
+      def self.uv_timer_cb(&block)
+        #        (handle)
+        params = [:pointer]
+        ::FFI::Function.new :void, params, blocking: true do |*args|
+          block.call(*args)
+        end
+      end
+      
+      attach_function :uv_strerror, [:int], :string, **opts
+      attach_function :uv_err_name, [:int], :string, **opts
+      
+      attach_function :uv_loop_init, [:uv_loop_ptr], :int, **opts
+      attach_function :uv_loop_close, [:uv_loop_ptr], :int, **opts
+      attach_function :uv_loop_alive, [:uv_loop_ptr], :int, **opts
+      
+      attach_function :uv_run, [:uv_loop_ptr, :uv_run_mode], :int, **opts
+      attach_function :uv_stop, [:uv_loop_ptr], :void, **opts
+      
+      attach_function :uv_poll_init, [:uv_loop_ptr, :uv_poll_ptr, :int], :int, **opts
+      attach_function :uv_poll_init_socket, [:uv_loop_ptr, :uv_poll_ptr, :uv_os_sock_t], :int, **opts
+      attach_function :uv_poll_start, [:uv_poll_ptr, :int, :uv_poll_cb_ptr], :int, **opts
+      attach_function :uv_poll_stop, [:uv_poll_ptr], :int, **opts
+      
+      attach_function :uv_signal_init, [:uv_loop_ptr, :uv_signal_ptr], :int, **opts
+      attach_function :uv_signal_start, [:uv_signal_ptr, :uv_signal_cb_ptr, :int], :int, **opts
+      attach_function :uv_signal_stop, [:uv_signal_ptr], :int, **opts
+      
+      attach_function :uv_timer_init, [:uv_loop_ptr, :uv_timer_ptr], :int, **opts
+      attach_function :uv_timer_start, [:uv_timer_ptr, :uv_timer_cb_ptr, :uint64, :uint64], :int, **opts
+      attach_function :uv_timer_stop, [:uv_timer_ptr], :int, **opts
+    end
+  end
+end

data/lib/bran/libuv/reactor.rb

@@ -0,0 +1,361 @@
+
+module Bran
+  module LibUV
+    class Reactor
+      
+      # Raised when an operation is performed on an already-destroyed Loop.
+      class DestroyedError < RuntimeError; end
+      
+      def initialize
+        @ptr = FFI.uv_loop_alloc
+        Util.error_check "creating the loop",
+          FFI.uv_loop_init(@ptr)
+        
+        @finalizer = self.class.create_finalizer_for(@ptr)
+        ObjectSpace.define_finalizer(self, @finalizer)
+        
+        @available_polls     = []
+        @running_reads       = {}
+        @running_writes      = {}
+        @fds_by_read_addr    = {}
+        @fds_by_write_addr   = {}
+        @on_readables        = {}
+        @on_writables        = {}
+        
+        @available_signals   = []
+        @running_signals     = {}
+        
+        @available_timers    = []
+        @running_timers      = {}
+        
+        @poll_read_callback  = FFI.uv_poll_cb(&method(:_poll_read_callback))
+        @poll_write_callback = FFI.uv_poll_cb(&method(:_poll_write_callback))
+        
+        # TODO: add more Ruby-compatible signal handlers by default?
+        signal_start(:INT) { @abort_signal = :INT; stop! }
+      end
+      
+      # Free the native resources associated with this object. This will
+      # be done automatically on garbage collection if not called explicitly.
+      def destroy
+        if @finalizer
+          @finalizer.call
+          ObjectSpace.undefine_finalizer(self)
+        end
+        @ptr = @finalizer = nil
+        
+        @available_polls      = \
+          @running_reads      = @running_writes      = \
+          @fds_by_read_addr   = @fds_by_write_addr   = \
+          @on_readables       = @on_writables        = \
+          @available_signals  = @running_signals     = \
+          @available_timers   = @running_timers      = \
+          @poll_read_callback = @poll_write_callback = nil
+        
+        self
+      end
+      
+      # @api private
+      def ptr
+        raise DestroyedError unless @ptr
+        @ptr
+      end
+      
+      # @api private
+      def self.create_finalizer_for(ptr)
+        Proc.new do
+          FFI.uv_loop_close(ptr)
+          # TODO: prevent running finalizer when loop hasn't been stopped?
+          ptr.free
+        end
+      end
+      
+      # Capture exceptions raised from callbacks, stopping the loop,
+      # capturing the exception to be re-raised outside the loop in #run!.
+      # @api private
+      def rescue_abort
+        yield
+      rescue Exception => ex
+        @abort_exception = ex
+        stop!
+      end
+      
+      # Run the libuv event loop in default (blocking) mode,
+      # running until stopped or until all handles are removed.
+      def run!
+        @abort_exception = nil
+        @abort_signal = nil
+        
+        rc = FFI.uv_run(ptr, :default)
+        
+        # If an exception or signal caused the stop, re-raise it here.
+        raise @abort_exception if @abort_exception
+        Process.kill(@abort_signal, Process.pid) if @abort_signal
+        
+        Util.error_check "running the loop in blocking mode", rc
+      end
+      
+      # Return true if there are active handles or request in the loop.
+      def stop!
+        FFI.uv_stop(ptr)
+      end
+      
+      # Push the given handler for the given fd, adding if necessary.
+      # If persistent is false, the handler will be popped after one trigger.
+      def push_readable(fd, handler, persistent = true)
+        ptr = ptr()
+        fd  = Integer(fd)
+        
+        # TODO: worry about readable vs writable mixing/overlap
+        if (readables = @on_readables[fd])
+          readables << [handler, persistent]
+          return
+        end
+        
+        poll = @available_polls.pop || FFI.uv_poll_alloc
+        @running_reads[fd]              = poll
+        @fds_by_read_addr[poll.address] = fd
+        @on_readables[fd]               = [[handler, persistent]]
+        
+        # TODO: investigate if need not init existing available_polls
+        Util.error_check "creating the poll readable entry",
+          FFI.uv_poll_init(ptr, poll, fd)
+        
+        Util.error_check "starting the poll readable entry",
+          FFI.uv_poll_start(poll, FFI::UV_READABLE, @poll_read_callback)
+        
+        fd
+      end
+      
+      # Push the given handler for the given fd, adding if necessary.
+      # If persistent is false, the handler will be popped after one trigger.
+      def push_writable(fd, handler, persistent = true)
+        ptr = ptr()
+        fd  = Integer(fd)
+        
+        # TODO: worry about writable vs writable mixing/overlap
+        if (writables = @on_writables[fd])
+          writables << [handler, persistent]
+          return
+        end
+        
+        poll = @available_polls.pop || FFI.uv_poll_alloc
+        @running_writes[fd]              = poll
+        @fds_by_write_addr[poll.address] = fd
+        @on_writables[fd]                = [[handler, persistent]]
+        
+        # TODO: investigate if need not init existing available_polls
+        Util.error_check "creating the poll writable entry",
+          FFI.uv_poll_init(ptr, poll, fd)
+        
+        Util.error_check "starting the poll writable entry",
+          FFI.uv_poll_start(poll, FFI::UV_WRITABLE, @poll_write_callback)
+        
+        fd
+      end
+      
+      # Remove the next readable handler for the given fd.
+      def pop_readable(fd)
+        fd = Integer(fd)
+        
+        readables = @on_readables[fd]
+        return unless readables
+          
+        readables.pop
+        return unless readables.empty?
+        
+        @on_readables.delete(fd)
+        poll = @running_reads.delete(fd)
+        @fds_by_read_addr.delete(poll.address)
+        
+        Util.error_check "stopping the poll readable entry",
+          FFI.uv_poll_stop(poll)
+        
+        @available_polls << poll
+        
+        nil
+      end
+      
+      # Remove the next writable handler for the given fd.
+      def pop_writable(fd)
+        fd = Integer(fd)
+        
+        writables = @on_writables[fd]
+        return unless writables
+          
+        writables.pop
+        return unless writables.empty?
+        
+        @on_writables.delete(fd)
+        poll = @running_writes.delete(fd)
+        @fds_by_write_addr.delete(poll.address)
+        
+        Util.error_check "stopping the poll writable entry",
+          FFI.uv_poll_stop(poll)
+        
+        @available_polls << poll
+        
+        nil
+      end
+      
+      # Start handling the given signal, running the given block when it occurs.
+      def signal_start(signo, &block)
+        ptr   = ptr()
+        signo = Signal.list.fetch(signo.to_s) unless signo.is_a?(Integer)
+        
+        signal_stop(signo) if @running_signals.has_key?(signo)
+        
+        callback = FFI.uv_signal_cb do |_, _|
+          rescue_abort do
+            block.call self, signo
+          end
+        end
+        
+        signal = @available_signals.pop || FFI.uv_signal_alloc
+        @running_signals[signo] = [signal, callback]
+        
+        # TODO: investigate if need not init existing available_signals
+        Util.error_check "creating the signal item",
+          FFI.uv_signal_init(ptr, signal)
+        
+        Util.error_check "starting the signal item",
+          FFI.uv_signal_start(signal, callback, signo)
+      end
+      
+      # Stop handling the given signal.
+      def signal_stop(signo)
+        signo = Signal.list.fetch(signo.to_s) unless signo.is_a?(Integer)
+        
+        signal, callback = @running_signals.delete(signo)
+        
+        return unless signal
+        
+        Util.error_check "stopping the signal item",
+          FFI.uv_signal_stop(signal)
+        
+        @available_signals << signal
+        
+        nil
+      end
+      
+      # Start a timer to run the given block after the given timeout.
+      # If a repeat_interval is given, after the first run, the block will be
+      # run repeatedly at that interval. If a repeat_interval is not given,
+      # or given as nil or 0, timer_cancel is called automatically at first run.
+      # Both timeout and repeat_interval should be given in seconds.
+      def timer_start(timeout, repeat_interval = nil, &block)
+        ptr = ptr()
+        
+        timeout = (timeout * 1000).ceil
+        
+        repeat = false
+        if repeat_interval and repeat_interval > 0
+          repeat_interval = (repeat_interval * 1000).ceil
+          repeat          = true
+        else
+          repeat_interval = 0
+        end
+        
+        raise ArgumentError, "callback block required" unless block
+        
+        timer = @available_timers.pop || FFI.uv_timer_alloc
+        id    = timer.address
+        
+        callback = FFI.uv_timer_cb do |_|
+          rescue_abort do
+            block.call self, id
+            
+            timer_cancel(id) unless repeat
+          end
+        end
+        
+        @running_timers[id] = [timer, callback]
+        
+        # TODO: investigate if need not init existing available_timers
+        Util.error_check "creating the timer item",
+          FFI.uv_timer_init(ptr, timer)
+        
+        Util.error_check "starting the timer item",
+          FFI.uv_timer_start(timer, callback, timeout, repeat_interval)
+        
+        id
+      end
+      
+      # Stop handling the given timer.
+      def timer_cancel(id)
+        id = Integer(id)
+        
+        timer, callback = @running_timers.delete(id)
+        
+        return unless timer
+        
+        Util.error_check "stopping the timer item",
+          FFI.uv_timer_stop(timer)
+        
+        @available_timers << timer
+        
+        nil
+      end
+      
+      # Start a timer to run the given block after the given timeout.
+      # The timer will be run just once, starting now.
+      def timer_oneshot(time, &block)
+        timer_start(time, &block)
+      end
+      
+      # Start a timer to wake the given fiber after the given timeout.
+      # The timer will be run just once, starting now.
+      def timer_oneshot_wake(time, fiber)
+        timer_start(time) { fiber.resume } # TODO: optimize this case
+      end
+      
+    private
+      
+      # Callback method called directly from FFI when an event is readable.
+      def _poll_read_callback(poll, rc, events)
+        rescue_abort do
+          fd        = @fds_by_read_addr.fetch(poll.address)
+          readables = @on_readables.fetch(fd)
+          
+          handler, persistent = readables.last
+          pop_readable(fd) unless persistent
+          
+          invoke_handler(handler, rc)
+        end
+      end
+      
+      # Callback method called directly from FFI when an event is writable.
+      def _poll_write_callback(poll, rc, events)
+        rescue_abort do
+          fd        = @fds_by_write_addr.fetch(poll.address)
+          writables = @on_writables.fetch(fd)
+          
+          handler, persistent = writables.last
+          pop_writable(fd) unless persistent
+          
+          invoke_handler(handler, rc)
+        end
+      end
+      
+      # Invoke the given handler, possibly converting the given rc to an error.
+      def invoke_handler(handler, rc)
+        case handler
+        when ::Fiber
+          if rc == 0
+            handler.resume nil
+          else
+            handler.resume Util.error_create("running the libuv loop", rc)
+          end
+        when ::Proc
+          if rc == 0
+            handler.call nil
+          else
+            error = Util.error_create("running the libuv loop", rc)
+            handler.call error
+          end
+        end
+      end
+      
+    end
+  end
+end

data/lib/bran/libuv/util.rb

@@ -0,0 +1,19 @@
+
+module Bran
+  module LibUV
+    module Util
+      
+      def self.error_check(action_description, rc)
+        raise error_create(action_description, rc) if rc < 0
+      end
+      
+      def self.error_create(action_description, rc)
+        # TODO: use appropriate SystemCallError exception class based on errno.
+        name = FFI.uv_err_name(rc)
+        desc = FFI.uv_strerror(rc)
+        RuntimeError.new("LibUV error - while #{action_description} - #{name} - #{desc}")
+      end
+      
+    end
+  end
+end

metadata

@@ -0,0 +1,162 @@
+--- !ruby/object:Gem::Specification
+name: bran
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Joe McIlvain
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-02-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.9.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.9.8
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.3'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: fivemat
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: A source of Fiber.
+email: joe.eli.mac@gmail.com
+executables: []
+extensions:
+- ext/libuv/Rakefile
+extra_rdoc_files: []
+files:
+- README.md
+- ext/libuv/Rakefile
+- lib/bran.rb
+- lib/bran/ext.rb
+- lib/bran/ext/io.rb
+- lib/bran/ext/rainbows.rb
+- lib/bran/ext/rainbows/bran.rb
+- lib/bran/ext/tcp_server.rb
+- lib/bran/fiber_manager.rb
+- lib/bran/libuv.rb
+- lib/bran/libuv/ffi.rb
+- lib/bran/libuv/reactor.rb
+- lib/bran/libuv/util.rb
+homepage: https://github.com/jemc/ruby-bran
+licenses:
+- All rights reserved.
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: bran
+test_files: []
+has_rdoc: