xchannel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3241b5fe46b009d7222e97c76fd892496d354755
+  data.tar.gz: bd09019fb519ebac631a621f16af75d0c7c5aab2
+SHA512:
+  metadata.gz: a7d37c874cf7b6a3a7a5371863cf2615bbabdd55bb8d16d6ce563407afb171c051b1c79004d1765e47e27ec849b12f5e54034af213a393d7e93bdb90e8cd4ecb
+  data.tar.gz: c95e63dc6666bffb84fb62582287e3bf411eece5cbdfcbc623840441844e85a42d5565b183b575c03880a9048bd5d2cd55996424e7226e0bebc7b205dbf5be60

data/.bundle/config

@@ -0,0 +1,3 @@
+---
+BUNDLE_PATH: ".gems"
+BUNDLE_DISABLE_SHARED_GEMS: '1'

data/.gitattributes

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

data/.gitignore

@@ -0,0 +1,2 @@
+.gems
+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,2 @@
+source 'http://rubygems.org'
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 rpag
+
+MIT License
+
+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/README.md

@@ -0,0 +1,57 @@
+__xchannel__
+
+xchannel is a library to assist with interprocess communication.
+It implements a channel that can be used to transmit ruby objects
+between ruby processes running on the same machine. It is implemented
+on top of an unbound, streamed unix socket.
+
+__Examples__
+
+__1.__
+
+basic fork example.
+[Marshal](http://rubydoc.info/stdlib/core/Marshal) is the serializer of choice.
+
+```ruby
+channel = XChannel.unix Marshal
+pid = fork do
+  channel.put Process.pid
+  channel.put 'Hello!'
+end
+Process.wait pid
+channel.get # => Fixnum
+channel.get # => 'Hello!'
+```
+
+__2.__
+
+avoid a blocking read
+
+```ruby
+channel = XChannel.unix Marshal
+pid = fork do
+  sleep 3
+  channel.put 42
+end
+until channel.readable?
+  # do something else
+end
+channel.get # => 42
+Process.wait pid
+```
+
+__Install__
+
+    $ gem install xchannel
+
+__Contributing__
+
+1. Fork it ( https://github.com/rpag/xchannel/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+__License__
+
+MIT. See LICENSE.txt.

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/xchannel.rb

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

data/lib/xchannel/unix_socket.rb

@@ -0,0 +1,144 @@
+require 'socket'
+class XChannel::UNIXSocket
+  SEP = '_$_'
+  if respond_to? :private_constant
+    private_constant :SEP
+  end
+
+  #
+  # @param [#dump,#load] serializer
+  #   An object who implements `.dump` and `.load` methods
+  #
+  # @return [XChannel::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 #put!)
+  #
+  # @param [Object] object
+  #   An object to add to a channel
+  #
+  def put(object)
+    put!(object, nil)
+  end
+
+  #
+  # @param
+  #   (see XChannel::UNIXSocket#put)
+  #
+  # @param [Fixnum] timeout
+  #   Number of seconds to wait before raising an exception
+  #
+  # @raise [IOError]
+  #   When channel is closed
+  #
+  # @raise [XChannel::TimeoutError]
+  #   When a write doesn't finish within the timeout
+  #
+  def put!(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 XChannel::TimeoutError, "timeout, waited #{timeout} seconds"
+    end
+  end
+
+  #
+  # Perform a blocking read 
+  #
+  # @raise
+  #   (see XChannel::UNIXSocket#get) 
+  #
+  # @return [Object]
+  #
+  def get
+    get!(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 [XChannel::TimeoutError]
+  #   When a read doesn't finish within the timeout
+  #
+  # @return [Object]
+  #
+  def get!(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 XChannel::TimeoutError, "timeout, waited #{timeout} seconds"
+    end
+  end
+
+  #
+  # @return [Object]
+  #
+  def last_msg
+    while readable?
+      @last_msg = get
+    end
+    @last_msg
+  end
+
+  #
+  # @return [Boolean]
+  #
+  def readable?
+    if closed?
+      false
+    else
+      readable, _ = IO.select [@reader], nil, nil, 0
+      !! readable
+    end
+  end
+end

data/lib/xchannel/version.rb

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

data/test/setup.rb

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

data/test/xchannel_unix_test.rb

@@ -0,0 +1,95 @@
+require_relative 'setup'
+class XChannelTest < Test::Unit::TestCase
+  def setup
+    serializer = Object.const_get ENV["SERIALIZER"] || "Marshal"
+    @channel = XChannel.unix serializer
+  end
+
+  def teardown
+    @channel.close unless @channel.closed?
+  end
+
+  def test_blocking_get
+    assert_raises Timeout::Error do
+      Timeout.timeout(1) { @channel.get }
+    end
+  end
+
+  def test_timeout_on_get
+    assert_raises XChannel::TimeoutError do
+      @channel.get! 1
+    end
+  end
+
+  def test_last_msg_after_read
+    @channel.put [42]
+    @channel.get
+    assert_equal [42], @channel.last_msg
+  end
+
+  def test_fork
+    pid = fork do
+      @channel.put [42]
+    end
+    Process.wait pid
+    assert_equal [42], @channel.get
+  end
+
+  def test_last_msg
+    @channel.put %w(a)
+    @channel.put %w(b)
+    assert_equal %w(b), @channel.last_msg
+  end
+
+  def test_last_msg_cache
+    @channel.put %w(a)
+    2.times { assert_equal %w(a), @channel.last_msg }
+    @channel.close
+    assert_equal %w(a), @channel.last_msg
+  end
+
+  def test_bust_last_msg_cache
+    @channel.put %w(a)
+    assert_equal %w(a), @channel.last_msg
+    @channel.put %w(b)
+    2.times { assert_equal %w(b), @channel.last_msg }
+  end
+
+  def test_put_on_closed_channel
+    @channel.close
+    assert_raises IOError do
+      @channel.put %w(a)
+    end
+  end
+
+  def test_get_on_closed_channel
+    @channel.close
+    assert_raises IOError do
+      @channel.get
+    end
+  end
+
+  def test_queued_messages
+    @channel.put %w(a)
+    @channel.put %w(b)
+    assert_equal %w(a), @channel.get
+    assert_equal %w(b), @channel.get
+  end
+
+  def test_readable_on_populated_channel
+    @channel.put %w(a)
+    @channel.put %w(b)
+    assert @channel.readable?
+  end
+
+  def test_readable_on_empty_channel
+    @channel.put %w(42)
+    @channel.get # discard
+    refute @channel.readable?
+  end
+
+  def test_readable_on_closed_channel
+    @channel.close
+    refute @channel.readable?
+  end
+end

data/xchannel.gemspec

@@ -0,0 +1,12 @@
+Kernel.require './lib/xchannel/version'
+Gem::Specification.new do |gem|
+  gem.name          = "xchannel"
+  gem.version       = XChannel::VERSION
+  gem.authors       = ["rpag"]
+  gem.email         = ["rpag@singletonclass.com"]
+  gem.description   = "IPC channel"
+  gem.summary       = gem.description
+  gem.homepage      = "https://github.com/rpag/xchannel"
+  gem.files         = `git ls-files`.split($/)
+  gem.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: xchannel
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- rpag
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-11-18 00:00:00.000000000 Z
+dependencies: []
+description: IPC channel
+email:
+- rpag@singletonclass.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".bundle/config"
+- ".gitattributes"
+- ".gitignore"
+- ".travis.yml"
+- ".yardopts"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/xchannel.rb
+- lib/xchannel/unix_socket.rb
+- lib/xchannel/version.rb
+- test/setup.rb
+- test/xchannel_unix_test.rb
+- xchannel.gemspec
+homepage: https://github.com/rpag/xchannel
+licenses: []
+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.2.2
+signing_key: 
+specification_version: 4
+summary: IPC channel
+test_files: []
+has_rdoc: