ffi-rxs 1.0.0

data/lib/ffi-rxs/util.rb

@@ -0,0 +1,105 @@
+
+module XS
+
+  # These methods don't belong to any specific class. They get included
+  # in the #Context, #Socket and #Poller classes.
+  #
+  module Util
+
+    # Returns true when +rc+ is greater than or equal to 0, false otherwise.
+    #
+    # We use the >= test because xs_poll() returns the number of sockets
+    # that had a read or write event triggered. So, a >= 0 result means
+    # it succeeded.
+    #
+    def self.resultcode_ok? rc
+      rc >= 0
+    end
+
+    # Returns the +errno+ as set by the libxs library.
+    #
+    def self.errno
+      LibXS.xs_errno
+    end
+
+    # Returns a string corresponding to the currently set #errno. These
+    # error strings are defined by libxs.
+    #
+    def self.error_string
+      LibXS.xs_strerror(errno).read_string
+    end
+
+    # Returns an array of the form [major, minor, patch] to represent the
+    # version of libxs.
+    #
+    # Class method! Invoke as:  XS::Util.version
+    #
+    def self.version
+      major = FFI::MemoryPointer.new :int
+      minor = FFI::MemoryPointer.new :int
+      patch = FFI::MemoryPointer.new :int
+      LibXS.xs_version major, minor, patch
+      [major.read_int, minor.read_int, patch.read_int]
+    end
+
+    # Attempts to bind to a random tcp port on +host+ up to +max_tries+
+    # times. Returns the port number upon success or nil upon failure.
+    #
+    def self.bind_to_random_tcp_port host = '127.0.0.1', max_tries = 500
+      tries = 0
+      rc = -1
+
+      while !resultcode_ok?(rc) && tries < max_tries
+        tries += 1
+        random = random_port
+        rc = socket.bind "tcp://#{host}:#{random}"
+      end
+
+      resultcode_ok?(rc) ? random : nil
+    end
+
+
+    private
+
+    # generate a random port between 10_000 and 65534
+    def self.random_port
+      rand(55534) + 10_000
+    end
+
+    # :doc:
+    # Called by most library methods to verify there were no errors during
+    # operation. If any are found, raise the appropriate #XSError.
+    #
+    # When no error is found, this method returns +true+ which is behavior
+    # used internally by #send and #recv.
+    #
+    def error_check source, result_code
+      if -1 == result_code
+        raise_error source, result_code
+      end
+
+      # used by Socket::send/recv, ignored by others
+      true
+    end
+
+    def raise_error source, result_code
+      if 'xs_init' == source || 'xs_socket' == source
+        raise ContextError.new source, result_code, XS::Util.errno, XS::Util.error_string
+
+      elsif ['xs_msg_init', 'xs_msg_init_data', 'xs_msg_copy', 'xs_msg_move'].include?(source)
+        raise MessageError.new source, result_code, XS::Util.errno, XS::Util.error_string
+
+      else
+        puts "else"
+        raise XSError.new source, result_code, -1,
+        "Source [#{source}] does not match any xs_* strings, rc [#{result_code}], errno [#{XS::Util.errno}], error_string [#{XS::Util.error_string}]"
+      end
+    end
+
+    def eagain?
+      EAGAIN == XS::Util.errno
+    end
+
+  end # module Util
+
+end # module XS

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

@@ -0,0 +1,105 @@
+
+module XS
+
+  # These methods don't belong to any specific class. They get included
+  # in the #Context, #Socket and #Poller classes.
+  #
+  module Util
+
+    # Returns true when +rc+ is greater than or equal to 0, false otherwise.
+    #
+    # We use the >= test because xs_poll() returns the number of sockets
+    # that had a read or write event triggered. So, a >= 0 result means
+    # it succeeded.
+    #
+    def self.resultcode_ok? rc
+      rc >= 0
+    end
+
+    # Returns the +errno+ as set by the libxs library.
+    #
+    def self.errno
+      LibXS.xs_errno
+    end
+
+    # Returns a string corresponding to the currently set #errno. These
+    # error strings are defined by libxs.
+    #
+    def self.error_string
+      LibXS.xs_strerror(errno).read_string
+    end
+
+    # Returns an array of the form [major, minor, patch] to represent the
+    # version of libzmq.
+    #
+    # Class method! Invoke as:  XS::Util.version
+    #
+    def self.version
+      major = FFI::MemoryPointer.new :int
+      minor = FFI::MemoryPointer.new :int
+      patch = FFI::MemoryPointer.new :int
+      LibXS.xs_version major, minor, patch
+      [major.read_int, minor.read_int, patch.read_int]
+    end
+
+    # Attempts to bind to a random tcp port on +host+ up to +max_tries+
+    # times. Returns the port number upon success or nil upon failure.
+    #
+    def self.bind_to_random_tcp_port host = '127.0.0.1', max_tries = 500
+      tries = 0
+      rc = -1
+
+      while !resultcode_ok?(rc) && tries < max_tries
+        tries += 1
+        random = random_port
+        rc = socket.bind "tcp://#{host}:#{random}"
+      end
+
+      resultcode_ok?(rc) ? random : nil
+    end
+
+
+    private
+
+    # generate a random port between 10_000 and 65534
+    def self.random_port
+      rand(55534) + 10_000
+    end
+
+    # :doc:
+    # Called by most library methods to verify there were no errors during
+    # operation. If any are found, raise the appropriate #XSError.
+    #
+    # When no error is found, this method returns +true+ which is behavior
+    # used internally by #send and #recv.
+    #
+    def error_check source, result_code
+      if -1 == result_code
+        raise_error source, result_code
+      end
+
+      # used by Socket::send/recv, ignored by others
+      true
+    end
+
+    def raise_error source, result_code
+      if 'xs_init' == source || 'xs_socket' == source
+        raise ContextError.new source, result_code, XS::Util.errno, XS::Util.error_string
+
+      elsif ['xs_msg_init', 'xs_msg_init_data', 'xs_msg_copy', 'xs_msg_move'].include?(source)
+        raise MessageError.new source, result_code, XS::Util.errno, XS::Util.error_string
+
+      else
+        puts "else"
+        raise XSError.new source, result_code, -1,
+        "Source [#{source}] does not match any xs_* strings, rc [#{result_code}], errno [#{XS::Util.errno}], error_string [#{XS::Util.error_string}]"
+      end
+    end
+
+    def eagain?
+      EAGAIN == XS::Util.errno
+    end
+
+  end # module Util
+
+end # module XS

data/lib/ffi-rxs/version.rb

@@ -0,0 +1,3 @@
+module XS
+  VERSION = "1.0.0"
+end

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

@@ -0,0 +1,3 @@
+module XS
+  VERSION = "0.1.0"
+end

data/lib/ffi-rxs.rb

@@ -0,0 +1,74 @@
+
+module XS
+
+  # :stopdoc:
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    @version ||= File.read(path('version.txt')).strip
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args, &block )
+    rv =  args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+    if block
+      begin
+        $LOAD_PATH.unshift LIBPATH
+        rv = block.call
+      ensure
+        $LOAD_PATH.shift
+      end
+    end
+    return rv
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args, &block )
+    rv = args.empty? ? PATH : ::File.join(PATH, args.flatten)
+    if block
+      begin
+        $LOAD_PATH.unshift PATH
+        rv = block.call
+      ensure
+        $LOAD_PATH.shift
+      end
+    end
+    return rv
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+    ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+end  # module XS
+
+# some code is conditionalized based upon what ruby engine we are
+# executing
+
+RBX = defined?(RUBY_ENGINE) && RUBY_ENGINE =~ /rbx/ ? true : false
+
+require 'ffi' unless RBX
+
+# the order of files is important
+%w(libc libxs constants util exceptions context message socket poll_items poll).each do |file|
+  require XS.libpath(['ffi-rxs', file])
+end

data/spec/context_spec.rb

@@ -0,0 +1,138 @@
+$: << "." # added for ruby 1.9.2 compatibilty; it doesn't include the current directory on the load path anymore
+
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+module XS
+
+
+  describe Context do
+
+    context "when initializing with factory method #create" do
+      include APIHelper
+
+      it "should set the :pointer accessor to non-nil" do
+        ctx = Context.create
+        ctx.pointer.should_not be_nil
+      end
+
+      it "should set the :context accessor to non-nil" do
+        ctx = Context.create
+        ctx.context.should_not be_nil
+      end
+
+      it "should set the :pointer and :context accessors to the same value" do
+        ctx = Context.create
+        ctx.pointer.should == ctx.context
+      end
+      
+      it "should define a finalizer on this object" do
+        ObjectSpace.should_receive(:define_finalizer)
+        ctx = Context.create
+      end
+    end # context initializing
+
+
+    context "when initializing with #new" do
+      include APIHelper
+
+      it "should set the :pointer accessor to non-nil" do
+        ctx = Context.new
+        ctx.pointer.should_not be_nil
+      end
+
+      it "should set the :context accessor to non-nil" do
+        ctx = Context.new
+        ctx.context.should_not be_nil
+      end
+
+      it "should set the :pointer and :context accessors to the same value" do
+        ctx = Context.new
+        ctx.pointer.should == ctx.context
+      end
+      
+      it "should define a finalizer on this object" do
+        ObjectSpace.should_receive(:define_finalizer)
+        ctx = Context.new
+      end
+    end # context initializing
+
+    context "when setting context options" do
+      include APIHelper
+      
+      it "gets EINVAL when option name is not recognized" do
+        ctx = Context.new
+        rc = ctx.setctxopt(XS::IDENTITY, 10)
+        Util.resultcode_ok?(rc).should be_false
+        XS::Util.errno.should == XS::EINVAL
+      end
+    end
+    
+    context "when setting IO_THREADS context option" do
+      include APIHelper
+      
+      it "should return unsuccessful code for zero io threads" do
+        ctx = Context.new
+        rc = ctx.setctxopt(XS::IO_THREADS, 0)
+        Util.resultcode_ok?(rc).should be_false
+        XS::Util.errno.should == XS::EINVAL
+      end
+      
+      it "should return unsuccessful code for negative io threads" do
+        ctx = Context.new
+        rc = ctx.setctxopt(XS::IO_THREADS, -1)
+        Util.resultcode_ok?(rc).should be_false
+        XS::Util.errno.should == XS::EINVAL
+      end
+      
+      it "should return successful code for positive io threads" do
+        ctx = Context.new
+        rc = ctx.setctxopt(XS::IO_THREADS, 10)
+        Util.resultcode_ok?(rc).should be_true
+      end
+    end # context set IO_THREADS
+
+
+    context "when setting MAX_SOCKETS context option" do
+      include APIHelper
+      
+      it "should return successful code for zero max sockets" do
+        ctx = Context.new
+        rc = ctx.setctxopt(XS::MAX_SOCKETS, 0)
+        Util.resultcode_ok?(rc).should be_true
+      end
+      
+      it "should return unsuccessful code for negative max sockets" do
+        ctx = Context.new
+        rc = ctx.setctxopt(XS::MAX_SOCKETS, -1)
+        Util.resultcode_ok?(rc).should be_false
+        XS::Util.errno.should == XS::EINVAL
+      end
+      
+      it "should return successful code for positive max sockets" do
+        ctx = Context.new
+        rc = ctx.setctxopt(XS::MAX_SOCKETS, 100)
+        Util.resultcode_ok?(rc).should be_true
+      end
+    end # context set MAX_SOCKETS
+
+    context "when terminating" do
+      it "should call xs_term to terminate the library's context" do
+        ctx = Context.new # can't use a shared context here because we are terminating it!
+        LibXS.should_receive(:xs_term).with(ctx.pointer).and_return(0)
+        ctx.terminate
+      end
+    end # context terminate
+
+
+    context "when allocating a socket" do
+      it "should return nil when allocation fails" do
+        ctx = Context.new
+        LibXS.stub!(:xs_socket => nil)
+        ctx.socket(XS::REQ).should be_nil
+      end
+    end # context socket
+
+  end # describe Context
+
+
+end # module XS

data/spec/message_spec.rb

@@ -0,0 +1,128 @@
+
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+module XS
+
+
+  describe Message do
+
+    context "when initializing with an argument" do
+
+      it "calls xs_msg_init_data()" do
+        LibXS.should_receive(:xs_msg_init_data)
+        message = Message.new "text"
+      end
+
+      it "should *not* define a finalizer on this object" do
+        ObjectSpace.should_not_receive(:define_finalizer)
+        Message.new "text"
+      end
+    end # context initializing with arg
+
+    context "when initializing *without* an argument" do
+
+      it "calls xs_msg_init()" do
+        LibXS.should_receive(:xs_msg_init).and_return(0)
+        message = Message.new
+      end
+
+      it "should *not* define a finalizer on this object" do
+        ObjectSpace.should_not_receive(:define_finalizer)
+        Message.new "text"
+      end
+    end # context initializing with arg
+
+
+    context "#copy_in_string" do
+      it "calls xs_msg_init_data()" do
+        message = Message.new "text"
+
+        LibXS.should_receive(:xs_msg_init_data)
+        message.copy_in_string("new text")
+      end
+
+      it "correctly finds the length of binary data by ignoring encoding" do
+        message = Message.new
+        message.copy_in_string("\x83\x6e\x04\x00\x00\x44\xd1\x81")
+        message.size.should == 8
+      end
+    end
+
+
+    context "#copy" do
+      it "calls xs_msg_copy()" do
+        message = Message.new "text"
+        copy = Message.new
+
+        LibXS.should_receive(:xs_msg_copy)
+        copy.copy(message)
+      end
+    end # context copy
+
+
+    context "#move" do
+      it "calls xs_msg_move()" do
+        message = Message.new "text"
+        copy = Message.new
+
+        LibXS.should_receive(:xs_msg_move)
+        copy.move(message)
+      end
+    end # context move
+
+
+    context "#size" do
+      it "calls xs_msg_size()" do
+        message = Message.new "text"
+
+        LibXS.should_receive(:xs_msg_size)
+        message.size
+      end
+    end # context size
+
+
+    context "#data" do
+      it "calls xs_msg_data()" do
+        message = Message.new "text"
+
+        LibXS.should_receive(:xs_msg_data)
+        message.data
+      end
+    end # context data
+
+
+    context "#close" do
+      it "calls xs_msg_close() the first time" do
+        message = Message.new "text"
+
+        LibXS.should_receive(:xs_msg_close)
+        message.close
+      end
+
+      it "*does not* call xs_msg_close() on subsequent invocations" do
+        message = Message.new "text"
+        message.close
+
+        LibXS.should_not_receive(:xs_msg_close)
+        message.close
+      end
+    end # context close
+
+  end # describe Message
+
+
+  describe ManagedMessage do
+
+    context "when initializing with an argument" do
+
+      it "should define a finalizer on this object" do
+        ObjectSpace.should_receive(:define_finalizer)
+        ManagedMessage.new "text"
+      end
+    end # context initializing
+
+
+  end # describe ManagedMessage
+
+
+end # module XS

data/spec/multipart_spec.rb

@@ -0,0 +1,108 @@
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+module XS
+  describe Socket do
+    context "multipart messages" do
+      before(:all) { @ctx = Context.new }
+      after(:all) { @ctx.terminate }
+
+      context "without identity" do
+        include APIHelper
+
+        before(:all) do
+          @rep = Socket.new(@ctx.pointer, XS::REP)
+          port = bind_to_random_tcp_port(@rep)
+
+          @req = Socket.new(@ctx.pointer, XS::REQ)
+          @req.connect("tcp://127.0.0.1:#{port}")
+        end
+
+        after(:all) do
+          @req.close
+          @rep.close
+        end
+
+        it "should be delivered between REQ and REP returning an array of strings" do
+          req_data, rep_data = [ "1", "2" ], [ "2", "3" ]
+
+          @req.send_strings(req_data)
+          strings = []
+          rc = @rep.recv_strings(strings)
+          strings.should == req_data
+
+          @rep.send_strings(rep_data)
+          strings = []
+          rc = @req.recv_strings(strings)
+          strings.should == rep_data
+        end
+
+        it "should be delivered between REQ and REP returning an array of messages" do
+          req_data, rep_data = [ "1", "2" ], [ "2", "3" ]
+
+          @req.send_strings(req_data)
+          messages = []
+          rc = @rep.recvmsgs(messages)
+          messages.each_with_index do |message, index|
+            message.copy_out_string.should == req_data[index]
+          end
+
+          @rep.send_strings(rep_data)
+          messages = []
+          rc = @req.recvmsgs(messages)
+          messages.each_with_index do |message, index|
+            message.copy_out_string.should == rep_data[index]
+          end
+        end
+      end
+
+        context "with identity" do
+          include APIHelper
+
+          before(:each) do # was :all
+            @rep = Socket.new(@ctx.pointer, XS::XREP)
+            port = bind_to_random_tcp_port(@rep)
+
+            @req = Socket.new(@ctx.pointer, XS::REQ)
+            @req.identity = 'foo'
+            @req.connect("tcp://127.0.0.1:#{port}")
+          end
+
+          after(:each) do # was :all
+            @req.close
+            @rep.close
+          end
+
+          it "should be delivered between REQ and REP returning an array of strings with an empty string as the envelope delimiter" do
+            req_data, rep_data = "hello", [ @req.identity, "", "ok" ]
+
+            @req.send_string(req_data)
+            strings = []
+            rc = @rep.recv_strings(strings)
+            strings.should == [ @req.identity, "", "hello" ]
+
+            @rep.send_strings(rep_data)
+            string = ''
+            rc = @req.recv_string(string)
+            string.should == rep_data.last
+          end
+
+          it "should be delivered between REQ and REP returning an array of messages with an empty string as the envelope delimiter" do
+            req_data, rep_data = "hello", [ @req.identity, "", "ok" ]
+
+            @req.send_string(req_data)
+            msgs = []
+            rc = @rep.recvmsgs(msgs)
+            msgs[0].copy_out_string.should == @req.identity
+            msgs[1].copy_out_string.should == ""
+            msgs[2].copy_out_string.should == "hello"
+
+            @rep.send_strings(rep_data)
+            msgs = []
+            rc = @req.recvmsgs(msgs)
+            msgs[0].copy_out_string.should == rep_data.last
+          end
+        end
+
+    end
+  end
+end