0mq 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5255703edba3faced3f3cc4cf411691e9a32657d
-  data.tar.gz: 70d06c893160bc3b09176cdec4626ec565e5637a
+  metadata.gz: 620201ac4bf75176a5ab224bd0bf0f0c3598e028
+  data.tar.gz: c360991d9cf9aa84873672945bd84252cb191263
 SHA512:
-  metadata.gz: 4114dc03d01056936a3bef1d4918e0f192616ee3283b4621d4249d4a4d8bb1dc05cc048ee7bf56a6c1167efc1636050839e59d83a762127d35c85e4df3558c62
-  data.tar.gz: 9f5f9c14f49b2f34e2018406d173f02627973cdea41f0a09873f99370d226bd8fc8b4ca454f789d50c804d81e6a50b0c73c8602ba3e83107d4c75f820ef71c1c
+  metadata.gz: 32f96897d84651bcc51e2e9037401ceb4839963a2523b534cbd9a46ffa6c4bad2f58a7c35e641505bc8a8b924a6153f5342bdd57c73a3cd9dc99f2e94f2572a2
+  data.tar.gz: 448432e63a64c0fe205e277c0040cb41fa13e90772b57c9f0b03c7eae8e100f16ae0afe011dd301df7c7f3d34e126e3647b03d2efda86a215ac7fdba736ec034

data/README.md

@@ -1,4 +1,5 @@
 # 0mq
+_Works like ZeroMQ. Feels like Ruby._
 
 [![Build Status](https://travis-ci.org/jemc/0mq.png)](https://travis-ci.org/jemc/0mq)
 [![Gem Version](https://badge.fury.io/rb/0mq.png)](http://badge.fury.io/rb/0mq)
@@ -21,10 +22,112 @@ Supported Ruby versions:
 
 ## Feature Requests / Bug Reports
 
-File them as issues or pull requests on [the github repository](https://github.com/jemc/0mq).
+File them as issues or pull requests on the [0mq github repository](https://github.com/jemc/0mq).
 
 ## Authors
 
 - Joe McIlvain
 
 - Alex McLain
+
+## Installation / Prerequisites
+
+- Requires the [libzmq library](http://zeromq.org/intro:get-the-software).
+
+- PGM (multicast) requires compiling libzmq with ./configure --with-pgm
+
+- Curve cryptography requires compiling libzmq with [libsodium](https://github.com/jedisct1/libsodium).
+	
+## ZeroMQ Documentation
+
+- Manual: http://zeromq.org/intro:read-the-manual
+
+- API: http://api.zeromq.org/
+
+## Code Examples
+
+### Using The 0mq Gem
+
+``` ruby
+require '0mq'
+```
+
+### Create A Socket
+
+Sockets can be created by specifying the [ZMQ socket type](http://api.zeromq.org/4-0:zmq-socket). Any errors will be raised as exceptions.
+
+``` ruby
+socket = ZMQ::Socket.new ZMQ::PULL
+socket.connect 'tcp://127.0.0.1:10000'
+```
+
+### Send And Receive Data
+
+``` ruby
+address = 'tcp://127.0.0.1:10000'
+
+push = ZMQ::Socket.new ZMQ::PUSH
+push.bind address
+
+pull = ZMQ::Socket.new ZMQ::PULL
+pull.connect address
+
+push.send_string 'test'
+
+string = pull.recv_string
+
+puts string
+```
+
+### Poll A Socket For Data
+
+``` ruby
+address = 'inproc://poll_example'
+
+pull = ZMQ::Socket.new ZMQ::PULL
+pull.bind address
+
+# Push a message after a delay.
+Thread.new do
+  push = ZMQ::Socket.new ZMQ::PUSH
+  push.connect address
+  sleep 3
+
+  push.send_string 'test'
+end
+
+# Check if pull has any data (it doesn't yet).
+# (Non-blocking demonstration.)
+result = ZMQ::Poll.poll_nonblock pull
+puts "No data available yet." if result.empty?
+
+# Do a blocking poll until the pull socket has data.
+ZMQ::Poll.poll pull do |socket, event|
+  puts socket.recv_string
+end
+```
+
+### Proxy Sockets
+
+A proxy can be used to funnel multiple endpoints into a single connection.
+See: [Pub-Sub Network with a Proxy](http://zguide.zeromq.org/page:all#The-Dynamic-Discovery-Problem)
+
+```ruby
+# ----------------     ----------------     ----------------     ----------------
+# | Endpoint REQ | --> | Proxy ROUTER | --> | Proxy DEALER | --> | Endpoint REP |
+# ----------------     ----------------     ----------------     ----------------
+
+# Create sockets.
+endpoint_req = ZMQ::Socket.new(ZMQ::REQ).tap    { |s| s.bind    'inproc://proxy_in'  }
+proxy_router = ZMQ::Socket.new(ZMQ::ROUTER).tap { |s| s.connect 'inproc://proxy_in'  }
+proxy_dealer = ZMQ::Socket.new(ZMQ::DEALER).tap { |s| s.bind    'inproc://proxy_out' }
+endpoint_rep = ZMQ::Socket.new(ZMQ::REP).tap    { |s| s.connect 'inproc://proxy_out' }
+
+# Create the proxy.
+Thread.new { ZMQ::Proxy.proxy proxy_router, proxy_dealer }
+
+# Send a message.
+endpoint_req.send_string 'test'
+
+puts endpoint_rep.recv_string
+```

data/lib/0mq.rb

@@ -6,3 +6,8 @@ require_relative '0mq/context'
 require_relative '0mq/socket'
 require_relative '0mq/proxy'
 require_relative '0mq/poll'
+require_relative '0mq/curve'
+require_relative '0mq/version'
+
+# :nodoc:
+module ZMQ; end

data/lib/0mq/context.rb

@@ -1,22 +1,26 @@
 
 module ZMQ
   
+  # The context object encapsulates all the global state associated
+  # with the library. 
   class Context
-    attr_reader :ptr
+    
+    # The FFI pointer to the context.
+    attr_reader :pointer
     
     def initialize
-      @ptr = LibZMQ.zmq_ctx_new
+      @pointer = LibZMQ.zmq_ctx_new
     end
     
     # Destroy the ØMQ context.
     def terminate
-      if @ptr
+      if @pointer
         rc = LibZMQ.version4?       ? 
-          LibZMQ.zmq_ctx_term(@ptr) : 
-          LibZMQ.zmq_term(@ptr)
+          LibZMQ.zmq_ctx_term(@pointer) : 
+          LibZMQ.zmq_term(@pointer)
         ZMQ.error_check true if rc == -1
         
-        @ptr = nil
+        @pointer = nil
       end
     end
     
@@ -26,8 +30,14 @@ module ZMQ
       ZMQ::Socket.new type, opts
     end
     
+    # Returns the context's FFI pointer.
+    def to_ptr
+      @pointer
+    end
+    
   end
   
+  # The default context to be used if another context is not provided.
   DefaultContext = Context.new
   
 end

data/lib/0mq/curve.rb

@@ -0,0 +1,26 @@
+
+module ZMQ
+  
+  # Secure authentication and confidentiality.
+  class Curve
+    
+    # Generate a keypair.
+    # Returns a hash with the :public and :private keys.
+    def self.keypair
+      public_key  = FFI::MemoryPointer.new :char, 41, true
+      private_key = FFI::MemoryPointer.new :char, 41, true
+      
+      rc = LibZMQ::zmq_curve_keypair public_key, private_key
+      
+      begin
+        ZMQ.error_check true if rc==-1
+      rescue Errno::EOPNOTSUPP
+        raise Errno::EOPNOTSUPP, "Curve requires libzmq to be compiled with libsodium."
+      end
+      
+      { public: public_key.read_string, private: private_key.read_string }
+    end
+    
+  end
+  
+end

data/lib/0mq/error_map.rb

@@ -1,18 +1,24 @@
 
 module ZMQ
   
+  # A hash of error number => exception class.
+  # Example: 1 => Errno::EPERM
   ErrorMap = Hash.new
   
   Errno.constants
-       .map    { |x| Errno.const_get x }
-       .select { |x| x.is_a?(Class) && x < SystemCallError }
-       .each   { |x| ErrorMap[x.const_get(:Errno)] = x }
+    .map    { |x| Errno.const_get x }
+    .select { |x| x.is_a?(Class) && x < SystemCallError }
+    .each   { |x| ErrorMap[x.const_get(:Errno)] = x }
   
+  
+  # Checks the libzmq global error number and raises it as an exception.
+  # Should be used after calling a libzmq resource that returns -1 on error.
+  # Example: ZMQ.error_check if rc == -1
   def self.error_check(adjust_backtrace=false)
     errno = LibZMQ.zmq_errno
     return true if errno == 25
     
-    # str = LibZMQ.zmq_strerror(errno).read_string
+    # TODO: Use adjust_backtrace
     str = ''
     raise ErrorMap[errno], str, caller[0...-2]
   end

data/lib/0mq/poll.rb

@@ -15,7 +15,8 @@ module ZMQ
     # See #initialize for parameters.
     # See #run for block and return value.
     def self.poll(*sockets, &block)
-      new(*sockets).tap { |poll| poll.run(&block) }
+      poller = new *sockets
+      poller.run &block
     end
     
     # Non-blocking version of poll.
@@ -58,7 +59,7 @@ module ZMQ
       # This is an easy way to reconnect PollItem to ZMQ::Socket without
       # having to store multiple dimensions in the socks hash.
       @socket_lookup = {}
-      @socks.each { |socket, event| @socket_lookup[socket.ptr.address] = socket }
+      @socks.each { |socket, event| @socket_lookup[socket.to_ptr.address] = socket }
       
       # Allocate space for C PollItem (zmq_pollitem_t) structs.
       @poll_structs = FFI::MemoryPointer.new LibZMQ::PollItem, @socks.count, true
@@ -90,7 +91,7 @@ module ZMQ
       
       # Poll
       rc = LibZMQ::zmq_poll @poll_structs, @poll_items.count, timeout
-      ZMQ.error_check true if rc==-1
+      ZMQ.error_check true if rc == -1
       
       # Create a hash of the items with triggered events.
       # (ZMQ::Socket => revents)
@@ -115,7 +116,10 @@ module ZMQ
 end
 
 
+# :nodoc:
 module LibZMQ
+  
+  # :nodoc:
   class PollItem
     
     # Get the event flags:
@@ -142,7 +146,7 @@ module LibZMQ
     # Set the socket to poll for events on.
     # Accepts a ZMQ::Socket or a pointer.
     def socket=(sock)
-      self[:socket] = sock.is_a?(FFI::Pointer) ? sock : sock.ptr
+      self[:socket] = sock.is_a?(FFI::Pointer) ? sock : sock.to_ptr
     end
     
   end

data/lib/0mq/proxy.rb

@@ -1,12 +1,24 @@
 
 module ZMQ
   
+  # The proxy connects a frontend socket to a backend socket. Conceptually,
+  # data flows from frontend to backend. Depending on the socket types,
+  # replies may flow in the opposite direction. The direction is conceptual
+  # only; the proxy is fully symmetric and there is no technical difference
+  # between frontend and backend.
   class Proxy
     
+    # Create a running proxy object.
+    def self.proxy(frontend, backend, capture = nil)
+      new(frontend, backend, capture).tap { |p| p.run }
+    end
+    
+    # Accepts a frontend, backend, and optional capture socket.
+    # See http://api.zeromq.org/4-0:zmq-proxy
     def initialize(frontend, backend, capture = nil)
-      @frontend = frontend.nil? ? nil : frontend.ptr
-      @backend  = backend.nil?  ? nil : backend.ptr
-      @capture  = capture.nil?  ? nil : capture.ptr
+      @frontend = frontend.nil? ? nil : frontend.to_ptr
+      @backend  = backend.nil?  ? nil : backend.to_ptr
+      @capture  = capture.nil?  ? nil : capture.to_ptr
     end
     
     # Block the current thread with the event loop of the proxy

data/lib/0mq/socket.rb

@@ -3,16 +3,22 @@ require_relative 'socket/options'
 
 module ZMQ
   
+  # See http://api.zeromq.org/4-0:zmq-socket
+  # Not thread safe.
   class Socket
-    attr_reader :ptr
+    
+    # The FFI pointer to the socket.
+    attr_reader :pointer
+    # The socket's ZMQ::Context.
     attr_reader :context
+    # The socket's ZeroMQ socket type (e.g. ZMQ::ROUTER).
     attr_reader :type
     
     def initialize(type, opts={})
       @context = opts.fetch :context, ZMQ::DefaultContext
       @type = type
-      @ptr = LibZMQ.zmq_socket @context.ptr, @type
-      ZMQ.error_check true if @ptr.null?
+      @pointer = LibZMQ.zmq_socket @context.pointer, @type
+      ZMQ.error_check true if @pointer.null?
       
       @msgptr = FFI::MemoryPointer.new LibZMQ::Message.size, 1, false
       
@@ -22,20 +28,20 @@ module ZMQ
     
     # Close the socket
     def close
-      if @ptr
+      if @pointer
         ObjectSpace.undefine_finalizer self
         @temp_buffers.clear if @temp_buffers
         
-        rc = LibZMQ.zmq_close @ptr
+        rc = LibZMQ.zmq_close @pointer
         ZMQ.error_check true if rc==-1
         
-        @ptr = nil
+        @pointer = nil
       end
     end
     
-    # Create a safe finalizer for the socket ptr to close on GC of the object
-    def self.finalizer(ptr, pid)
-      Proc.new { LibZMQ.zmq_close ptr if Process.pid == pid }
+    # Create a safe finalizer for the socket pointer to close on GC of the object
+    def self.finalizer(pointer, pid)
+      Proc.new { LibZMQ.zmq_close pointer if Process.pid == pid }
     end
     
     # Get the socket type name as a symbol
@@ -45,25 +51,25 @@ module ZMQ
     
     # Bind to an endpoint
     def bind(endpoint)
-      rc = LibZMQ.zmq_bind @ptr, endpoint
+      rc = LibZMQ.zmq_bind @pointer, endpoint
       ZMQ.error_check true if rc==-1
     end
     
     # Connect to an endpoint
     def connect(endpoint)
-      rc = LibZMQ.zmq_connect @ptr, endpoint
+      rc = LibZMQ.zmq_connect @pointer, endpoint
       ZMQ.error_check true if rc==-1
     end
     
     # Unbind from an endpoint
     def unbind(endpoint)
-      rc = LibZMQ.zmq_unbind @ptr, endpoint
+      rc = LibZMQ.zmq_unbind @pointer, endpoint
       ZMQ.error_check true if rc==-1
     end
     
-    # Disconnect to an endpoint
+    # Disconnect from an endpoint
     def disconnect(endpoint)
-      rc = LibZMQ.zmq_disconnect @ptr, endpoint
+      rc = LibZMQ.zmq_disconnect @pointer, endpoint
       ZMQ.error_check true if rc==-1
     end
     
@@ -77,7 +83,7 @@ module ZMQ
       rc = LibZMQ.zmq_msg_init_data @msgptr, @msgbuf, size, LibC::Free, nil
       ZMQ.error_check true if rc==-1
       
-      rc = LibZMQ.zmq_sendmsg @ptr, @msgptr, flags
+      rc = LibZMQ.zmq_sendmsg @pointer, @msgptr, flags
       ZMQ.error_check true if rc==-1
       
       rc = LibZMQ.zmq_msg_close @msgptr
@@ -89,7 +95,7 @@ module ZMQ
       rc = LibZMQ.zmq_msg_init @msgptr
       ZMQ.error_check true if rc==-1
       
-      rc = LibZMQ.zmq_recvmsg @ptr, @msgptr, flags
+      rc = LibZMQ.zmq_recvmsg @pointer, @msgptr, flags
       ZMQ.error_check true if rc==-1
       
       str = LibZMQ.zmq_msg_data(@msgptr)
@@ -163,7 +169,7 @@ module ZMQ
         value = valptr
       end
       
-      rc = LibZMQ.zmq_setsockopt @ptr, option, value, value.size
+      rc = LibZMQ.zmq_setsockopt @pointer, option, value, value.size
       ZMQ.error_check true if rc==-1
       
       value
@@ -176,7 +182,7 @@ module ZMQ
       
       value, size = get_opt_pointers type
       
-      rc = LibZMQ.zmq_getsockopt @ptr, option, value, size
+      rc = LibZMQ.zmq_getsockopt @pointer, option, value, size
       ZMQ.error_check true if rc==-1
       
       if type == :string
@@ -188,6 +194,11 @@ module ZMQ
       end
     end
     
+    # Returns the socket's FFI pointer.
+    def to_ptr
+      @pointer
+    end
+    
   private
     
     def get_opt_pointers(type)

data/lib/0mq/version.rb

@@ -0,0 +1,102 @@
+
+module ZMQ
+  
+  # Returns a ZMQ::Version object containing the libzmq library version.
+  def self.version
+    ZMQ::Version
+  end
+  
+  
+  # libzmq library version.
+  class Version
+    
+    @version = LibZMQ.version
+    
+    private_class_method :new
+    
+    class << self
+      
+      # :nodoc:
+      def major
+        @version[:major]
+      end
+      
+      # :nodoc:
+      def minor
+        @version[:minor]
+      end
+      
+      # :nodoc:
+      def patch
+        @version[:patch]
+      end
+      
+      # :nodoc:
+      def to_s
+        "#{major}.#{minor}.#{patch}"
+      end
+      
+      # :nodoc:
+      def inspect
+        "#{super} \"#{to_s}\""
+      end
+      
+      # Compare this version to another version.
+      # Examples: "3.2.0", "3.2", "3", 3
+      def <=>(value)
+        expression = /(?<major>\d+)(\.(?<minor>\d+))?(\.(?<patch>\d+))?/
+        
+        # Convert both versions into an array of [major, minor, patch].
+        this_version = self.to_s
+        other_version = value.to_s
+        
+        this_version =~ expression
+        this_set = $~.captures.map { |item| item.to_i if item }.select { |item| item }
+        
+        other_version =~ expression
+        other_set = $~.captures.map { |item| item.to_i if item }.select { |item| item }
+        
+        # Compare each section (major/minor/patch) of the version number.
+        other_set.count.times do |i|
+          return  1 if this_set[i] > other_set[i]
+          return -1 if this_set[i] < other_set[i]
+        end
+        
+        0 # If the iterator didn't return, the versions are equal.
+      end
+      
+      # :nodoc:
+      def ==(value)
+        (self <=> value) == 0 ? true : false
+      end
+      
+      # :nodoc:
+      def !=(value)
+        (self <=> value) != 0 ? true : false
+      end
+      
+      # :nodoc:
+      def >(value)
+        (self <=> value) == 1 ? true : false
+      end
+      
+      # :nodoc:
+      def >=(value)
+        (self <=> value) != -1 ? true : false
+      end
+      
+      # :nodoc:
+      def <(value)
+        (self <=> value) == -1 ? true : false
+      end
+      
+      # :nodoc:
+      def <=(value)
+        (self <=> value) != 1 ? true : false
+      end
+      
+    end
+    
+  end
+  
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: 0mq
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Joe McIlvain
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-04 00:00:00.000000000 Z
+date: 2014-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi-rzmq-core
@@ -119,11 +119,13 @@ files:
 - README.md
 - lib/0mq.rb
 - lib/0mq/context.rb
+- lib/0mq/curve.rb
 - lib/0mq/error_map.rb
 - lib/0mq/poll.rb
 - lib/0mq/proxy.rb
 - lib/0mq/socket.rb
 - lib/0mq/socket/options.rb
+- lib/0mq/version.rb
 homepage: https://github.com/jemc/0mq/
 licenses:
 - MIT