ffi-rxs 1.0.0

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+
+*.rbc
+.redcar/

data/AUTHORS.txt

@@ -0,0 +1,21 @@
+Chuck Remes, github: chuckremes
+
+Andrew Cholakian, github: andrewvc
+
+Ar Vicco, github: arvicco
+
+Ben Mabey, github: bmabey
+
+Julien Ammous, github: schmurfy
+
+Zachary Belzer, github: zbelzer
+
+Cory Forsyth, github: bantic
+
+Stefan Kaes, github: skaes
+
+Dmitry Ustalov, github: eveel
+
+Patrik Sundberg, github: sundbp
+
+Chris Duncan, github: celldee

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/README.rdoc

@@ -0,0 +1,86 @@
+ffi-rxs
+    by Chris Duncan
+
+== DESCRIPTION:
+
+This gem wraps the Crossroads I/O networking library using the Ruby FFI (foreign
+function interface). It's a pure Ruby wrapper so this gem can be loaded
+and run by any Ruby runtime that supports FFI. That's all of them:
+MRI 1.9.x, Rubinius and JRuby.
+
+Crossroads I/O is a fork of ZeroMQ. This gem is a re-working of the ffi-rzmq gem
+created by Chuck Remes to provide bindings for the Crossroads I/O libxs C library
+instead of the ZeroMQ libzmq library. The gem auto-configures itself to expose
+the API conforming to the loaded C library. 
+
+== FEATURES/PROBLEMS:
+
+This gem needs to be tested in the wild. Please kick its tyres and give it a
+good thrashing. It is inevitable that bugs will be discovered, so please open 
+issues for them here or fork this project, fix them, and send me a pull
+request.
+
+The 'ffi' gem has dropped support for MRI 1.8.x. Since this project relies
+on that gem to load and run this code, then this project does not support
+MRI 1.8.x. I recommend JRuby for the best performance and stability.
+
+== REQUIREMENTS:
+
+  * Crossroads I/O version 1.0.0 or later.
+  
+The Crossroads I/O library must be installed on your system in a well-known location
+like /usr/local/lib. This is the default for new Crossroads I/O installs.
+
+Future releases may include the library as a C extension built at
+time of installation.
+
+  * ffi (>= 1.0.0)
+  
+Do *not* run this gem under MRI with an old 'ffi' gem. It will crash randomly and
+you will be sad.
+
+== INSTALL:
+
+A full gem has been released to Rubygems.org as of release 1.0.0.
+Make sure the Crossroads I/O library is already installed on your system.
+
+ % gem install ffi-rxs # should grab the latest release
+
+
+To build from git master:
+
+ % git clone git://github.com/celldee/ffi-rxs
+ % cd ffi-rxs
+ % gem build ffi-rxs.gemspec
+ % gem install ffi-rxs-*.gem
+ 
+
+NOTE for Windows users!
+In order for this gem to find the libxs.dll, it *must* be on the Windows PATH. Google
+for "modify windows path" for instructions on how to do that if you are unfamiliar with
+that activity.
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2011 - 2012 Chuck Remes, Chris Duncan and contributors
+
+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/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task :default => :spec

data/ext/README

@@ -0,0 +1,5 @@
+To avoid loading a system-wide Crossroads I/O library, place
+the C libraries here. This lets you run your Ruby
+code with a Crossroads C library build that is different
+from the system-wide one. This can be handy for
+rolling upgrades or testing.

data/ffi-rxs.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "ffi-rxs/version"
+
+Gem::Specification.new do |s|
+  s.name        = "ffi-rxs"
+  s.version     = XS::VERSION
+  s.authors     = ["Chris Duncan"]
+  s.email       = ["celldee@gmail.com"]
+  s.homepage    = "http://github.com/celldee/ffi-rxs"
+  s.summary     = %q{This gem wraps the Crossroads I/O networking library using Ruby FFI (foreign function interface).}
+  s.description = %q{This gem wraps the Crossroads I/O networking library using the ruby FFI (foreign
+function interface). It's a pure ruby wrapper so this gem can be loaded
+and run by any ruby runtime that supports FFI. That's all of them:
+MRI 1.9.x, Rubinius and JRuby.}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency "ffi"
+  s.add_development_dependency "rspec", ["~> 2.6"]
+  s.add_development_dependency "rake"
+end

data/lib/ffi-rxs/constants.rb

@@ -0,0 +1,104 @@
+module XS
+  # Set up all of the constants
+  
+  # Context options
+  MAX_SOCKETS = 1
+  IO_THREADS = 2
+  
+  #  Socket types
+  PAIR = 0
+  PUB = 1
+  SUB = 2
+  REQ = 3
+  REP = 4
+  XREQ = 5
+  XREP = 6
+  PULL = 7
+  PUSH = 8
+  XPUB = 9
+  XSUB = 10
+  DEALER = XREQ
+  ROUTER = XREP
+
+  SocketTypeNameMap = {
+    PAIR => "PAIR",
+    PUB => "PUB",
+    SUB => "SUB",
+    REQ => "REQ",
+    REP => "REP",
+    PULL => "PULL",
+    PUSH => "PUSH",
+    XREQ => "XREQ",
+    XREP => "XREP",
+    ROUTER => "ROUTER",
+    DEALER => "DEALER",
+    XPUB => "XPUB",
+    XSUB => "XSUB"
+  }
+
+  #  Socket options
+  AFFINITY = 4
+  IDENTITY = 5
+  SUBSCRIBE = 6
+  UNSUBSCRIBE = 7
+  RATE = 8
+  RECOVERY_IVL = 9
+  SNDBUF = 11
+  RCVBUF = 12
+  RCVMORE = 13
+  FD = 14
+  EVENTS = 15
+  TYPE = 16
+  LINGER = 17
+  RECONNECT_IVL = 18
+  BACKLOG = 19
+  RECONNECT_IVL_MAX = 21
+  MAXMSGSIZE = 22
+  SNDHWM = 23
+  RCVHWM = 24
+  MULTICAST_HOPS = 25
+  RCVTIMEO = 27
+  SNDTIMEO = 28
+
+  #  Send/recv options
+  DONTWAIT = 1
+  SNDMORE = 2
+  SNDLABEL = 4
+  NonBlocking = DONTWAIT
+
+  #  I/O multiplexing
+
+  POLL = 1
+  POLLIN = 1
+  POLLOUT = 2
+  POLLERR = 4
+
+  #  Socket errors
+  EAGAIN = Errno::EAGAIN::Errno
+  EFAULT = Errno::EFAULT::Errno
+  EINVAL = Errno::EINVAL::Errno
+  EMFILE = Errno::EMFILE::Errno
+  ENOMEM = Errno::ENOMEM::Errno
+  ENODEV = Errno::ENODEV::Errno
+  
+  # XS errors
+  HAUSNUMERO     = 156384712
+  EMTHREAD       = (HAUSNUMERO + 50)
+  EFSM           = (HAUSNUMERO + 51)
+  ENOCOMPATPROTO = (HAUSNUMERO + 52)
+  ETERM          = (HAUSNUMERO + 53)
+
+  # Rescue unknown constants and use the Crossroads defined values
+  # Usually only happens on Windows though some don't resolve on
+  # OSX too (ENOTSUP)
+  ENOTSUP         = Errno::ENOTSUP::Errno rescue (HAUSNUMERO + 1)
+  EPROTONOSUPPORT = Errno::EPROTONOSUPPORT::Errno rescue (HAUSNUMERO + 2)
+  ENOBUFS         = Errno::ENOBUFS::Errno rescue (HAUSNUMERO + 3)
+  ENETDOWN        = Errno::ENETDOWN::Errno rescue (HAUSNUMERO + 4)
+  EADDRINUSE      = Errno::EADDRINUSE::Errno rescue (HAUSNUMERO + 5)
+  EADDRNOTAVAIL   = Errno::EADDRNOTAVAIL::Errno rescue (HAUSNUMERO + 6)
+  ECONNREFUSED    = Errno::ECONNREFUSED::Errno rescue (HAUSNUMERO + 7)
+  EINPROGRESS     = Errno::EINPROGRESS::Errno rescue (HAUSNUMERO + 8)
+  ENOTSOCK        = Errno::ENOTSOCK::Errno rescue (HAUSNUMERO + 9)
+  EINTR           = Errno::EINTR::Errno rescue (HAUSNUMERO + 10)
+end # module XS

data/lib/ffi-rxs/constants.rb~

@@ -0,0 +1,100 @@
+module XS
+  # Set up all of the constants
+  
+  #  Socket types
+  PAIR = 0
+  PUB = 1
+  SUB = 2
+  REQ = 3
+  REP = 4
+  XREQ = 5
+  XREP = 6
+  PULL = 7
+  PUSH = 8
+  XPUB = 9
+  XSUB = 10
+  DEALER = XREQ
+  ROUTER = XREP
+
+  SocketTypeNameMap = {
+    PAIR => "PAIR",
+    PUB => "PUB",
+    SUB => "SUB",
+    REQ => "REQ",
+    REP => "REP",
+    PULL => "PULL",
+    PUSH => "PUSH",
+    XREQ => "XREQ",
+    XREP => "XREP",
+    ROUTER => "ROUTER",
+    DEALER => "DEALER",
+    XPUB => "XPUB",
+    XSUB => "XSUB"
+  }
+
+  #  Socket options
+  AFFINITY = 4
+  IDENTITY = 5
+  SUBSCRIBE = 6
+  UNSUBSCRIBE = 7
+  RATE = 8
+  RECOVERY_IVL = 9
+  SNDBUF = 11
+  RCVBUF = 12
+  RCVMORE = 13
+  FD = 14
+  EVENTS = 15
+  TYPE = 16
+  LINGER = 17
+  RECONNECT_IVL = 18
+  BACKLOG = 19
+  RECONNECT_IVL_MAX = 21
+  MAXMSGSIZE = 22
+  SNDHWM = 23
+  RCVHWM = 24
+  MULTICAST_HOPS = 25
+  RCVTIMEO = 27
+  SNDTIMEO = 28
+
+  #  Send/recv options
+  DONTWAIT = 1
+  SNDMORE = 2
+  SNDLABEL = 4
+  NonBlocking = DONTWAIT
+
+  #  I/O multiplexing
+
+  POLL = 1
+  POLLIN = 1
+  POLLOUT = 2
+  POLLERR = 4
+
+  #  Socket errors
+  EAGAIN = Errno::EAGAIN::Errno
+  EFAULT = Errno::EFAULT::Errno
+  EINVAL = Errno::EINVAL::Errno
+  EMFILE = Errno::EMFILE::Errno
+  ENOMEM = Errno::ENOMEM::Errno
+  ENODEV = Errno::ENODEV::Errno
+  
+  # XS errors
+  HAUSNUMERO     = 156384712
+  EMTHREAD       = (HAUSNUMERO + 50)
+  EFSM           = (HAUSNUMERO + 51)
+  ENOCOMPATPROTO = (HAUSNUMERO + 52)
+  ETERM          = (HAUSNUMERO + 53)
+
+  # Rescue unknown constants and use the Crossroads defined values
+  # Usually only happens on Windows though some don't resolve on
+  # OSX too (ENOTSUP)
+  ENOTSUP         = Errno::ENOTSUP::Errno rescue (HAUSNUMERO + 1)
+  EPROTONOSUPPORT = Errno::EPROTONOSUPPORT::Errno rescue (HAUSNUMERO + 2)
+  ENOBUFS         = Errno::ENOBUFS::Errno rescue (HAUSNUMERO + 3)
+  ENETDOWN        = Errno::ENETDOWN::Errno rescue (HAUSNUMERO + 4)
+  EADDRINUSE      = Errno::EADDRINUSE::Errno rescue (HAUSNUMERO + 5)
+  EADDRNOTAVAIL   = Errno::EADDRNOTAVAIL::Errno rescue (HAUSNUMERO + 6)
+  ECONNREFUSED    = Errno::ECONNREFUSED::Errno rescue (HAUSNUMERO + 7)
+  EINPROGRESS     = Errno::EINPROGRESS::Errno rescue (HAUSNUMERO + 8)
+  ENOTSOCK        = Errno::ENOTSOCK::Errno rescue (HAUSNUMERO + 9)
+  EINTR           = Errno::EINTR::Errno rescue (HAUSNUMERO + 10)
+end # module XS

data/lib/ffi-rxs/context.rb

@@ -0,0 +1,153 @@
+
+module XS
+
+
+  # Recommended to use the default for +io_threads+
+  # since most programs will not saturate I/O. 
+  #
+  # The rule of thumb is to make +io_threads+ equal to the number 
+  # gigabits per second that the application will produce.
+  #
+  # The +io_threads+ number specifies the size of the thread pool
+  # allocated by 0mq for processing incoming/outgoing messages.
+  #
+  # Returns a context object when allocation succeeds. It's necessary
+  # for passing to the
+  # #Socket constructor when allocating new sockets. All sockets
+  # live within a context.
+  #
+  # Also, Sockets should *only* be accessed from the thread where they
+  # were first created. Do *not* pass sockets between threads; pass
+  # in the context and allocate a new socket per thread. If you must
+  # use threads, then make sure to execute a full memory barrier (e.g.
+  # mutex) as you pass a socket from one thread to the next.
+  #
+  # To connect sockets between contexts, use +inproc+ or +ipc+
+  # transport and set up a Crossroads socket between them. This is also the
+  # recommended technique for allowing sockets to communicate between
+  # threads.
+  #
+  #  context = XS::Context.create
+  #  if context
+  #    socket = context.socket(XS::REQ)
+  #    if socket
+  #      ...
+  #    else
+  #      STDERR.puts "Socket allocation failed"
+  #    end
+  #  else
+  #    STDERR.puts "Context allocation failed"
+  #  end
+  #
+  #
+  class Context
+    include XS::Util
+
+    attr_reader :context, :pointer
+
+    def self.create
+      new() rescue nil
+    end
+    
+    # Use the factory method Context#create to make contexts.
+    #
+    def initialize
+      @sockets = []
+      @context = LibXS.xs_init()
+      @pointer = @context
+      error_check 'xs_init', (@context.nil? || @context.null?) ? -1 : 0
+
+      define_finalizer
+    end
+    
+    # Set options on this context.
+    #
+    # Context options take effect only if set with setctxopt() prior to
+    # creating the first socket in a given context with socket().
+    #
+    # Valid +name+ values that take a numeric +value+ are:
+    #  XS::IO_THREADS
+    #  XS::MAX_SOCKETS
+    #
+    # Returns 0 when the operation completed successfully.
+    # Returns -1 when this operation failed.
+    #
+    # With a -1 return code, the user must check XS.errno to determine the
+    # cause.
+    #
+    #  rc = context.setctxopt(XS::IO_THREADS, 10)
+    #  XS::Util.resultcode_ok?(rc) ? puts("succeeded") : puts("failed")
+    #
+    def setctxopt name, value, length = nil
+      length = 4
+      pointer = LibC.malloc length
+      pointer.write_int value
+
+      rc = LibXS.xs_setctxopt @context, name, pointer, length
+      LibC.free(pointer) unless pointer.nil? || pointer.null?
+      rc
+    end
+
+    # Call to release the context and any remaining data associated
+    # with past sockets. This will close any sockets that remain
+    # open; further calls to those sockets will return -1 to indicate
+    # the operation failed.
+    #
+    # Returns 0 for success, -1 for failure.
+    #
+    def terminate
+      unless @context.nil? || @context.null?
+        remove_finalizer
+        rc = LibXS.xs_term @context
+        @context = nil
+        @sockets = nil
+        rc
+      else
+        0
+      end
+    end
+
+    # Short-cut to allocate a socket for a specific context.
+    #
+    # Takes several +type+ values:
+    #   #XS::REQ
+    #   #XS::REP
+    #   #XS::PUB
+    #   #XS::SUB
+    #   #XS::PAIR
+    #   #XS::PULL
+    #   #XS::PUSH
+    #   #XS::DEALER
+    #   #XS::ROUTER
+    #
+    # Returns a #XS::Socket when the allocation succeeds, nil
+    # if it fails.
+    #
+    def socket type
+      sock = nil
+      begin
+        sock = Socket.new @context, type
+      rescue ContextError => e
+        sock = nil
+      end
+      
+      sock
+    end
+
+
+    private
+
+    def define_finalizer
+      ObjectSpace.define_finalizer(self, self.class.close(@context))
+    end
+
+    def remove_finalizer
+      ObjectSpace.undefine_finalizer self
+    end
+
+    def self.close context
+      Proc.new { LibXS.xs_term context unless context.null? }
+    end
+  end
+
+end # module XS

data/lib/ffi-rxs/context.rb~

@@ -0,0 +1,155 @@
+
+module XS
+
+
+  # Recommended to use the default for +io_threads+
+  # since most programs will not saturate I/O. 
+  #
+  # The rule of thumb is to make +io_threads+ equal to the number 
+  # gigabits per second that the application will produce.
+  #
+  # The +io_threads+ number specifies the size of the thread pool
+  # allocated by 0mq for processing incoming/outgoing messages.
+  #
+  # Returns a context object when allocation succeeds. It's necessary
+  # for passing to the
+  # #Socket constructor when allocating new sockets. All sockets
+  # live within a context.
+  #
+  # Also, Sockets should *only* be accessed from the thread where they
+  # were first created. Do *not* pass sockets between threads; pass
+  # in the context and allocate a new socket per thread. If you must
+  # use threads, then make sure to execute a full memory barrier (e.g.
+  # mutex) as you pass a socket from one thread to the next.
+  #
+  # To connect sockets between contexts, use +inproc+ or +ipc+
+  # transport and set up a Crossroads socket between them. This is also the
+  # recommended technique for allowing sockets to communicate between
+  # threads.
+  #
+  #  context = XS::Context.create
+  #  if context
+  #    socket = context.socket(XS::REQ)
+  #    if socket
+  #      ...
+  #    else
+  #      STDERR.puts "Socket allocation failed"
+  #    end
+  #  else
+  #    STDERR.puts "Context allocation failed"
+  #  end
+  #
+  #
+  class Context
+    include XS::Util
+
+    attr_reader :context, :pointer
+
+    def self.create
+      new() rescue nil
+    end
+    
+    # Use the factory method Context#create to make contexts.
+    #
+    def initialize
+      @sockets = []
+      @context = LibXS.xs_init()
+      @pointer = @context
+      error_check 'xs_init', (@context.nil? || @context.null?) ? -1 : 0
+
+      define_finalizer
+    end
+    
+    # Set options on this context.
+    #
+    # Context options take effect only if set with setctxopt() prior to
+    # creating the first socket in a given context with socket().
+    #
+    # Valid +name+ values that take a numeric +value+ are:
+    #  XS::IO_THREADS
+    #  XS::MAX_SOCKETS
+    #
+    # Returns 0 when the operation completed successfully.
+    # Returns -1 when this operation failed.
+    #
+    # With a -1 return code, the user must check XS.errno to determine the
+    # cause.
+    #
+    #  rc = context.setctxopt(XS::IO_THREADS, 10)
+    #  XS::Util.resultcode_ok?(rc) ? puts("succeeded") : puts("failed")
+    #
+    def setctxopt name, value, length = nil
+      #if (name == XS::IO_THREADS) || (name == XS::MAX_SOCKETS)
+        length = 4
+        pointer = LibC.malloc length
+        pointer.write_int value
+      #end
+
+      rc = LibXS.xs_setctxopt @context, name, pointer, length
+      LibC.free(pointer) unless pointer.nil? || pointer.null?
+      rc
+    end
+
+    # Call to release the context and any remaining data associated
+    # with past sockets. This will close any sockets that remain
+    # open; further calls to those sockets will return -1 to indicate
+    # the operation failed.
+    #
+    # Returns 0 for success, -1 for failure.
+    #
+    def terminate
+      unless @context.nil? || @context.null?
+        remove_finalizer
+        rc = LibXS.xs_term @context
+        @context = nil
+        @sockets = nil
+        rc
+      else
+        0
+      end
+    end
+
+    # Short-cut to allocate a socket for a specific context.
+    #
+    # Takes several +type+ values:
+    #   #XS::REQ
+    #   #XS::REP
+    #   #XS::PUB
+    #   #XS::SUB
+    #   #XS::PAIR
+    #   #XS::PULL
+    #   #XS::PUSH
+    #   #XS::DEALER
+    #   #XS::ROUTER
+    #
+    # Returns a #XS::Socket when the allocation succeeds, nil
+    # if it fails.
+    #
+    def socket type
+      sock = nil
+      begin
+        sock = Socket.new @context, type
+      rescue ContextError => e
+        sock = nil
+      end
+      
+      sock
+    end
+
+
+    private
+
+    def define_finalizer
+      ObjectSpace.define_finalizer(self, self.class.close(@context))
+    end
+
+    def remove_finalizer
+      ObjectSpace.undefine_finalizer self
+    end
+
+    def self.close context
+      Proc.new { LibXS.xs_term context unless context.null? }
+    end
+  end
+
+end # module XS

data/lib/ffi-rxs/device.rb~

@@ -0,0 +1,28 @@
+module ZMQ
+  if LibZMQ.version2?
+    class Device
+      attr_reader :device
+      
+      def self.create(device_type, frontend, backend)
+        dev = nil
+        begin
+          dev = new device_type, frontend, backend
+        rescue ArgumentError
+          dev = nil
+        end
+        
+        dev
+      end
+
+      def initialize(device_type,frontend,backend)
+        [["frontend", frontend],["backend", backend]].each do |name,socket|
+          unless socket.is_a?(ZMQ::Socket)
+            raise ArgumentError, "Expected a ZMQ::Socket, not a #{socket.class} as the #{name}"
+          end
+        end
+
+        LibZMQ.zmq_device(device_type, frontend.socket, backend.socket)
+      end
+    end
+  end
+end