zchannel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6b734e305c5b58ff2748a914726a87b17096ae28
+  data.tar.gz: fbc41b5a2ffd5323197761ffcb3298c829dd79db
+SHA512:
+  metadata.gz: ac889c3e6f4704c42e97e58da6268c5a06e1b6defd670b2c43984e008def714ef9b59f1ef1041454f3005e62ffde5f4eca65359a7d135bda64c4447cc8d808c9
+  data.tar.gz: 9a5c36e1c85da9783fb05703eb7271b951aec14e99008db97bdfc6e0d5bfa0954ea7f4a2634abbb1db98d428460d06754a49881d58eff796e635033238857da9

data/.gitattributes

@@ -0,0 +1 @@
+* text eol=lf

data/.gitignore

@@ -0,0 +1,3 @@
+.gems
+.bundle
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,17 @@
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+  - rbx-19mode
+# - ruby-head
+
+env:
+  - REDIS=1 SERIALIZER=YAML
+  - REDIS=1 SERIALIZER=Marshal
+  - REDIS=1 SERIALIZER=JSON
+
+services:
+  - redis-server
+
+notifications:
+  email: true 

data/.yardopts

@@ -0,0 +1,5 @@
+-m markdown -M redcarpet
+-
+README.md
+LICENSE.txt
+ChangeLog.txt

data/Gemfile

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

data/README.md

@@ -0,0 +1,56 @@
+__zchannel__
+
+zchannel is a library that assists with InterProcess Communication, or
+IPC for short. It provides a high level and easy to use API for sending
+Ruby objects between processes that are running on the same machine.
+A channel is implemented on top of an unbound UNIXSocket, and objects
+are serialized with a serializer of your choosing although the examples
+use the "Marshal" serializer, which is available without any extra
+dependencies.
+
+__Examples__
+
+__1.__
+
+```ruby
+chan = ZChannel.unix Marshal
+Process.wait fork { chan.send "Hello, world!" }
+chan.recv # => "Hello, world!"
+```
+
+__Install__
+
+* Rubygems
+
+```
+$ gem install zchannel
+```
+
+* Bundler
+
+```ruby
+gem "zchannel", "~> 0.1"
+```
+
+__License__
+
+```
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain.
+
+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 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 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.test_files = Dir['test/*_test.rb']
+end
+task default: :test

data/lib/zchannel/unix_socket.rb

@@ -0,0 +1,139 @@
+require 'socket'
+class ZChannel::UNIXSocket
+  SEP = '_$_'  if respond_to? :private_constant
+
+  #
+  # @param [#dump,#load] serializer
+  #   An object who implements `.dump` and `.load` methods
+  #
+  # @return [ZChannel::UNIXSocket]
+  #
+  def initialize(serializer = Marshal)
+    @serializer = serializer
+    @last_msg = nil
+    @reader, @writer = ::UNIXSocket.pair :STREAM
+  end
+
+  #
+  # @return [Boolean]
+  #   Returns true when a channel is closed
+  #
+  def closed?
+    @reader.closed? and @writer.closed?
+  end
+
+  #
+  # Close the channel
+  #
+  # @raise [IOError]
+  #   When a channel is already closed
+  #
+  # @return [Boolean]
+  #   Returns true on success
+  #
+  def close
+    if closed?
+      raise IOError, 'closed channel'
+    else
+      @reader.close
+      @writer.close
+      true
+    end
+  end
+
+  #
+  # @raise [IOError]
+  #   (see #send!)
+  #
+  # @param [Object] object
+  #   An object to add to a channel
+  #
+  def send(object)
+    send!(object, nil)
+  end
+
+  #
+  # @param
+  #   (see ZChannel::UNIXSocket#send)
+  #
+  # @param [Fixnum] timeout
+  #   Number of seconds to wait before raising an exception
+  #
+  # @raise [IOError]
+  #   When channel is closed
+  #
+  # @raise [ZChannel::TimeoutError]
+  #   When a write doesn't finish within the timeout
+  #
+  def send!(object, timeout = 0.1)
+    if @writer.closed?
+      raise IOError, 'closed channel'
+    end
+    _, writable, _ = IO.select nil, [@writer], nil, timeout
+    if writable
+      msg = @serializer.dump(object)
+      writable[0].syswrite "#{msg}#{SEP}"
+    else
+      raise ZChannel::TimeoutError, "timeout, waited #{timeout} seconds"
+    end
+  end
+
+  #
+  # Perform a blocking read
+  #
+  # @raise
+  #   (see ZChannel::UNIXSocket#recv)
+  #
+  # @return [Object]
+  #
+  def recv
+    recv!(nil)
+  end
+
+  #
+  # Perform a read with a timeout
+  #
+  # @param [Fixnum] timeout
+  #   Number of seconds to wait before raising an exception
+  #
+  # @raise [IOError]
+  #   When channel is closed
+  #
+  # @raise [ZChannel::TimeoutError]
+  #   When a read doesn't finish within the timeout
+  #
+  # @return [Object]
+  #
+  def recv!(timeout = 0.1)
+    if @reader.closed?
+      raise IOError, 'closed channel'
+    end
+    readable, _ = IO.select [@reader], nil, nil, timeout
+    if readable
+      msg = readable[0].readline(SEP).chomp SEP
+      @last_msg = @serializer.load msg
+    else
+      raise ZChannel::TimeoutError, "timeout, waited #{timeout} seconds"
+    end
+  end
+
+  #
+  # @return [Object]
+  #
+  def last_msg
+    @last_msg = recv while readable?
+    @last_msg
+  end
+
+  #
+  # @return [Boolean]
+  #
+  def readable?
+    if closed?
+      false
+    else
+      readable, _ = IO.select [@reader], nil, nil, 0
+      !! readable
+    end
+  end
+end

data/lib/zchannel/version.rb

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

data/lib/zchannel.rb

@@ -0,0 +1,15 @@
+module ZChannel
+  TimeoutError = Class.new(StandardError)
+  require_relative "zchannel/unix_socket"
+
+  #
+  # @param 
+  #   (see UNIXSocket#initialize).
+  #
+  # @return
+  #   (see UNIXSocket#initialize)
+  #
+  def self.unix(serializer = Marshal)
+    UNIXSocket.new(serializer)
+  end
+end

data/test/setup.rb

@@ -0,0 +1,3 @@
+require 'bundler/setup'
+require 'test/unit'
+Bundler.require :default, :test

data/test/zchannel_test.rb

@@ -0,0 +1,94 @@
+require_relative 'setup'
+class ZChannelTest < Test::Unit::TestCase
+  def setup
+    @chan = ZChannel.unix Object.const_get(ENV["SERIALIZER"] || "Marshal")
+  end
+
+  def teardown
+    @chan.close unless @chan.closed?
+  end
+
+  def test_blocking_recv
+    assert_raises Timeout::Error do
+      Timeout.timeout(1) { @chan.recv }
+    end
+  end
+
+  def test_timeout_on_recv
+    assert_raises ZChannel::TimeoutError do
+      @chan.recv! 1
+    end
+  end
+
+  def test_last_msg_after_read
+    @chan.send [42]
+    @chan.recv
+    assert_equal [42], @chan.last_msg
+  end
+
+  def test_fork
+    pid = fork do
+      @chan.send [42]
+    end
+    Process.wait pid
+    assert_equal [42], @chan.recv
+  end
+
+  def test_last_msg
+    @chan.send %w(a)
+    @chan.send %w(b)
+    assert_equal %w(b), @chan.last_msg
+  end
+
+  def test_last_msg_cache
+    @chan.send %w(a)
+    2.times { assert_equal %w(a), @chan.last_msg }
+    @chan.close
+    assert_equal %w(a), @chan.last_msg
+  end
+
+  def test_bust_last_msg_cache
+    @chan.send %w(a)
+    assert_equal %w(a), @chan.last_msg
+    @chan.send %w(b)
+    2.times { assert_equal %w(b), @chan.last_msg }
+  end
+
+  def test_send_on_closed_channel
+    @chan.close
+    assert_raises IOError do
+      @chan.send %w(a)
+    end
+  end
+
+  def test_recv_on_closed_channel
+    @chan.close
+    assert_raises IOError do
+      @chan.recv
+    end
+  end
+
+  def test_queued_messages
+    @chan.send %w(a)
+    @chan.send %w(b)
+    assert_equal %w(a), @chan.recv
+    assert_equal %w(b), @chan.recv
+  end
+
+  def test_readable_on_populated_channel
+    @chan.send %w(a)
+    @chan.send %w(b)
+    assert @chan.readable?
+  end
+
+  def test_readable_on_empty_channel
+    @chan.send %w(42)
+    @chan.recv # discard
+    refute @chan.readable?
+  end
+
+  def test_readable_on_closed_channel
+    @chan.close
+    refute @chan.readable?
+  end
+end

data/zchannel.gemspec

@@ -0,0 +1,13 @@
+Kernel.require './lib/zchannel/version'
+Gem::Specification.new do |gem|
+  gem.name          = "zchannel"
+  gem.version       = ZChannel::VERSION
+  gem.authors       = ["jazzonmymind"]
+  gem.email         = ["robert@jazzonmymind.xyz"]
+  gem.description   = "Provides a high level and easy to use API for sending objects between Ruby processes"
+  gem.summary       = gem.description
+  gem.homepage      = "https://github.com/jazzonmymind/zchannel.rb"
+  gem.licenses      = ["Nonstandard"]
+  gem.files         = `git ls-files`.split($/)
+  gem.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: zchannel
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- jazzonmymind
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-08-09 00:00:00.000000000 Z
+dependencies: []
+description: Provides a high level and easy to use API for sending objects between
+  Ruby processes
+email:
+- robert@jazzonmymind.xyz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitattributes"
+- ".gitignore"
+- ".travis.yml"
+- ".yardopts"
+- Gemfile
+- README.md
+- Rakefile
+- lib/zchannel.rb
+- lib/zchannel/unix_socket.rb
+- lib/zchannel/version.rb
+- test/setup.rb
+- test/zchannel_test.rb
+- zchannel.gemspec
+homepage: https://github.com/jazzonmymind/zchannel.rb
+licenses:
+- Nonstandard
+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.5.1
+signing_key: 
+specification_version: 4
+summary: Provides a high level and easy to use API for sending objects between Ruby
+  processes
+test_files: []
+has_rdoc: