ichannel 6.0.0 → 6.1.0

data/.pryrc

@@ -0,0 +1 @@
+require "./lib/ichannel"

data/ChangeLog.txt

@@ -1,3 +1,14 @@
+== HEAD
+	- Redis#last_msg, UNIXSocket#last_msg changes.
+	The last_msg method returns the last value read by #get when a channel is
+	not readable.
+
+	- change IChannel from being a class to a module.
+	There's no need to create an instance of IChannel anymore.
+
+	- Add IChannel::Redis.
+	Add Redis as a backend.
+
 == v0.6.0
 	- IChannel::UNIXSocket can now be serialized by Marshal.
 	IChannel::UNIXSocket can be serialized by Marshal but there's a gotcha: it

data/Gemfile

@@ -1,7 +1,10 @@
 source 'http://rubygems.org'
 group :development do
-  gem 'rake'
-  gem 'redcarpet'
-  gem 'yard'
+  gem "pry"
+  gem "rake"
+  gem "redcarpet"
+  gem "yard"
+  gem "foreman"
 end
+gem "redis"
 gemspec

data/Procfile

@@ -0,0 +1 @@
+redis: redis-server

data/README.md

@@ -1,6 +1,5 @@
 __OVERVIEW__
 
-
 | Project         | ichannel   
 |:----------------|:--------------------------------------------------
 | Homepage        | https://github.com/robgleeson/ichannel
@@ -11,25 +10,33 @@ __OVERVIEW__
 
 __DESCRIPTION__
 
-ichannel simplifies interprocess communication by providing a bi-directional
-channel that can be used to transport ruby objects between processes on the same 
-machine. All communication on a channel occurs on a streamed UNIXSocket that a 
-channel uses to queues its messages (ruby objects), and also to ensure that 
-messages are received in the order they are sent.
+ichannel is a channel for interprocess communication between ruby processes on
+the same machine(or network). The basic premise is that you can "put" a ruby 
+object onto the channel and on the other end(maybe in a different process, 
+or maybe on a different machine) you can "get" the object from the channel.
+
+The two main modes of transport are a UNIXSocket(streamed) or [redis](https://redis.io).
+A unix socket is fast and operates without any external dependencies but it
+can't go beyond a single machine. A channel that uses redis can operate between
+different machines. And incase you're wondering ichannel uses a 
+redis [list](http://redis.io/commands#list) to queue messages. 
+
+The last topic I feel I should talk about before the examples is serialization. 
+A ruby object is serialized(on write) and deserialized(on read) when passing
+through a channel. A channel can use any serializer that implements the dump and
+load methods but the default is [Marshal](http://ruby-doc.org/core-2.0/Marshal.html).
+There are also a number of objects that cannot be serialized (such as IO, 
+anonymous classes/modules, Proc, …) but I've found most of the time I send
+simple objects like Hash.
 
-Underneath the hood ruby objects are serialized when writing and reading from the 
-underlying UNIXSocket. A ruby object is serialized before a write, and it is 
-deserialized after a read. The choice of serializer is left up to you, though. 
-A serializer can be any object that implements `dump` and `load` -- two methods 
-that are usually implemented by serializers written in ruby.
 
 __EXAMPLES__
 
 __1.__
 
 A demo of how to pass ruby objects through a channel and also between processes.  
-[Marshal](http://rubydoc.info/stdlib/core/Marshal) is the serializer of choice 
-in this example: 
+[Marshal](http://rubydoc.info/stdlib/core/Marshal) is the serializer of choice, 
+and a streamed UNIXSocket is mode of transport:
 
 ```ruby
 channel = IChannel.unix Marshal
@@ -45,7 +52,8 @@ channel.get # => 'Hello!'
 __2.__
 
 Knowing when a channel is readable can be useful so that you can avoid a
-blocking read. This (bad) example demonstrates how to do that:
+blocking read on the underlying UNIXSocket. This (bad) example demonstrates 
+how to do that:
 
 ```ruby
 channel = IChannel.unix Marshal 
@@ -62,6 +70,19 @@ Process.wait pid
 
 __3.__
 
+A demo of how to use ichannel with Redis:
+
+```ruby
+channel = IChannel.redis
+channel.put %w(a)
+
+# In another process, far away…
+channel = IChannel.redis
+channel.get # => ["a"]
+```
+
+__4.__
+
 MessagePack doesn't implement `dump` or `load` but a wrapper can be easily
 written:
 
@@ -93,6 +114,13 @@ _unsupported_
 
 __INSTALL__
 
+If you plan on using redis you'll need to install the 'redis' gem. It's
+optional:
+
+    $ gem install redis
+
+And to finish:
+
     $ gem install ichannel
 
 __SEE ALSO__

data/lib/ichannel/redis.rb

@@ -0,0 +1,154 @@
+class IChannel::Redis
+
+  #
+  # @param [#dump,#load] serializer
+  #   A serializer.
+  #
+  # @param [Hash] options
+  #   A Hash of options to pass onto the redis-rb client.
+  #
+  # @return [IChannel::Redis]
+  #
+  def initialize(serializer, options)
+    @serializer = serializer
+    @key = options.delete(:key) || "channel"
+    @redis = ::Redis.new(options)
+    @last_msg = nil
+    @closed = false
+  end
+
+  #
+  # @return [Boolean]
+  #   Returns true when the channel is closed.
+  #
+  def closed?
+    @closed
+  end
+
+  #
+  # Close the channel.
+  #
+  # @return [Boolean]
+  #   Returns true when the channel has been closed.
+  #
+  def close
+    unless closed?
+      @redis.quit
+      @last_msg = nil
+      @closed = true
+    end
+  end
+
+  #
+  # Add an object to the channel.
+  #
+  # @param [Object] object
+  #   The object to add to the channel.
+  #
+  # @raise [IOError]
+  #   When the channel is closed.
+  #
+  # @return
+  #   (see Redis#write!)
+  #
+  def write(object)
+    write!(object, nil)
+  end
+  alias_method :put, :write
+
+  #
+  # Add an object to the channel.
+  #
+  # @param [Object] object
+  #   The object to add to the channel.
+  #
+  # @param [Fixnum] timeout
+  #   The amount of time to wait for the write to complete.
+  #
+  # @raise [IOError]
+  #   When the channel is closed.
+  #
+  # @raise [Timeout::Error]
+  #   When the write does not complete in time.
+  #
+  # @return [void]
+  #
+  def write!(object, timeout = 0.1)
+    if closed?
+      raise IOError, 'The channel cannot be written to (closed)'
+    end
+    Timeout.timeout(timeout) do
+      dump = @serializer.dump object
+      @redis.lpush @key, dump
+    end
+  end
+  alias_method :put!, :write!
+
+  #
+  # Read an object from the channel.
+  #
+  # @raise [IOError]
+  #   When the channel is closed or empty.
+  #
+  # @return
+  #   (see Redis#recv!)
+  #
+  def recv
+    recv! nil
+  end
+  alias_method :get, :recv
+
+  #
+  # @param [Fixnum] timeout
+  #   The amount of time to wait for the read to complete.
+  #
+  # @raise [IOError]
+  #   When the channel is closed or empty.
+  #
+  # @raise [Timeout::Error]
+  #   When the read does not complete in time.
+  #
+  # @return [Object]
+  #   The object read from the channel.
+  #
+  def recv!(timeout = 0.1)
+    if closed?
+      raise IOError, 'The channel cannot be read from (closed).'
+    elsif empty?
+      raise IOError, 'The channel cannot be read from (empty).'
+    else
+      Timeout.timeout(timeout) do
+        dump = @redis.rpop @key
+        @last_msg = @serializer.load dump
+      end
+    end
+  end
+  alias_method :get!, :recv!
+
+  #
+  # @return [Object]
+  #   Returns the last message written to the channel.
+  #
+  def last_msg
+    while readable?
+      @last_msg = get
+    end
+    @last_msg
+  end
+
+  #
+  # @return [Boolean]
+  #   Returns true when the channel is empty.
+  #
+  def empty?
+    @redis.llen(@key) == 0
+  end
+
+  #
+  # @return [Boolean]
+  #   Returns true when the channel is readable.
+  #
+  def readable?
+    !closed? && !empty?
+  end
+end

data/lib/ichannel/unix_socket.rb

@@ -1,5 +1,5 @@
 require 'socket'
-class IChannel
+module IChannel
   class UNIXSocket
     SEP = '_$_'
     if respond_to? :private_constant
@@ -10,6 +10,8 @@ class IChannel
     # @param [#dump,#load] serializer
     #   Any object that implements dump, & load.
     #
+    # @return [IChannel::UNIXSocket]
+    #
     def initialize(serializer = Marshal, adapter_options)
       @serializer = serializer
       @last_msg = nil
@@ -139,7 +141,7 @@ class IChannel
       readable, _ = IO.select [@reader], nil, nil, timeout
       if readable
         msg = readable[0].readline(SEP).chomp SEP
-        @serializer.load msg
+        @last_msg = @serializer.load msg
       else
         raise IOError, 'The channel cannot be read from.'
       end

data/lib/ichannel/version.rb

@@ -1,3 +1,3 @@
-class IChannel
-  VERSION = "6.0.0"
+module IChannel
+  VERSION = "6.1.0"
 end

data/lib/ichannel.rb

@@ -1,11 +1,30 @@
-class IChannel
+module IChannel
+  require 'redis'
   require_relative "ichannel/unix_socket"
+  require_relative "ichannel/redis"
 
-  def self.unix(options)
-    UNIXSocket.new(options)
+  #
+  # @param
+  #   (see UNIXSocket#initialize)
+  #
+  # @return
+  #   (see UNIXSocket#initialize)
+  #
+  def self.unix(serializer = Marshal, options = {})
+    UNIXSocket.new serializer, options
   end
 
-  def self.redis(options)
-    raise NotImplementedError
+  #
+  # @param
+  #   (see Redis#initialize)
+  #
+  # @return
+  #   (see Redis#initialize)
+  #
+  def self.redis(serializer = Marshal, options = {})
+    unless defined?(::Redis)
+      require 'redis'
+    end
+    Redis.new serializer, options
   end
 end

data/test/ichannel_redis_test.rb

@@ -0,0 +1,17 @@
+require_relative 'setup'
+require_relative 'ichannel_unix_test'
+class IChannelRedisTest < IChannelUNIXTest
+  def setup
+    serializer = Object.const_get ENV["SERIALIZER"] || "Marshal"
+    @channel = IChannel.redis serializer
+  end
+
+  def teardown
+    key = @channel.instance_variable_get :@key
+    @channel.instance_variable_get(:@redis).del(key)
+    @channel.close
+  end
+
+  def test_serialization() end
+  def test_serialization_in_fork() end
+end

data/test/{ichannel_class_test.rb → ichannel_unix_test.rb}

@@ -1,5 +1,5 @@
 require_relative 'setup'
-class IChannelTest < Test::Unit::TestCase
+class IChannelUNIXTest < Test::Unit::TestCase
   def setup
     serializer = Object.const_get ENV["SERIALIZER"] || "Marshal"
     @channel = IChannel.unix serializer
@@ -26,6 +26,21 @@ class IChannelTest < Test::Unit::TestCase
     end
   end
 
+  def test_last_msg_after_read
+    @channel.put 42
+    @channel.get
+    assert_equal 42, @channel.last_msg
+  end
+
+  def test_serialization_in_fork
+    dump = Marshal.dump(@channel)
+    pid = fork do
+      Marshal.load(dump).put 42
+    end
+    Process.wait pid
+    assert_equal 42, @channel.get
+  end
+
   def test_serialization
     @channel.put 42
     dump = Marshal.dump @channel

data/test/setup.rb

@@ -1,5 +1,6 @@
+require "bundler"
+Bundler.require :default
 require_relative '../lib/ichannel'
-
 require 'yaml'
 require 'json'
 require 'test/unit'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ichannel
 version: !ruby/object:Gem::Version
-  version: 6.0.0
+  version: 6.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-20 00:00:00.000000000 Z
+date: 2013-05-03 00:00:00.000000000 Z
 dependencies: []
 description: ! "A modern and easy-to-use interprocess communication \n    primitive."
 email:
@@ -20,18 +20,22 @@ extra_rdoc_files: []
 files:
 - .gitattributes
 - .gitignore
+- .pryrc
 - .travis.yml
 - .yardopts
 - ChangeLog.txt
 - Gemfile
 - LICENSE.txt
+- Procfile
 - README.md
 - Rakefile
 - ichannel.gemspec
 - lib/ichannel.rb
+- lib/ichannel/redis.rb
 - lib/ichannel/unix_socket.rb
 - lib/ichannel/version.rb
-- test/ichannel_class_test.rb
+- test/ichannel_redis_test.rb
+- test/ichannel_unix_test.rb
 - test/setup.rb
 homepage: https://github.com/robgleeson/ichannel
 licenses: []
@@ -47,7 +51,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4148613930352415051
+      hash: 3267569127984942618
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -56,7 +60,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4148613930352415051
+      hash: 3267569127984942618
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -64,6 +68,7 @@ signing_key:
 specification_version: 3
 summary: A modern and easy-to-use interprocess communication  primitive.
 test_files:
-- test/ichannel_class_test.rb
+- test/ichannel_redis_test.rb
+- test/ichannel_unix_test.rb
 - test/setup.rb
 has_rdoc: