ichannel 6.1.1.1 → 7.0.0

data/ChangeLog.txt

@@ -1,3 +1,17 @@
+== v7.0.0
+   - IChannel::UNIXSocket#get! raises Timeout::Error
+   When a read does not complete in time a Timeout::Error will be 
+   raised (IChannel::Redis#get! already has this behavior).
+
+   - IChannel::Redis#get is a blocking read.
+   IChannel::Redis#get now blocks on read(by using the BRPOP command)
+
+   - Remove serialization support for IChannel::UNIXSocket.
+   The support is severely limited and the source of too many
+   edge cases to continue support. Even if serialization was
+   limited to a single machine it only works under specific
+   circumstances.
+
 == v6.1.1.1
    - Documentation improvements
 
@@ -24,15 +38,15 @@
    - IChannel::UNIXSocket can now be serialized by Marshal.
    IChannel::UNIXSocket can be serialized by Marshal but there's a gotcha: it
    only really works on the same machine between one or more Ruby processes.
-   The UNIXSocket#marshal_dump method is implemented to dump the FDs in an array, 
-   so this feature won't fair well across different machines or time but I've 
+   The UNIXSocket#marshal_dump method is implemented to dump the FDs in an array,
+   so this feature won't fair well across different machines or time but I've
    found this feature useful nonetheless.
 
    - add IChannel.unix(…)
    Returns an instance of IChannel::UNIXSocket.
 
    - add IChannel::UNIXSocket
-   rename IChannel as IChannel::UNIXSocket in preparation for multiple 
+   rename IChannel as IChannel::UNIXSocket in preparation for multiple
    backends(UNIXSocket, Redis, …).
 
 == v5.2.0
@@ -50,29 +64,29 @@
 
 == v5.1.0
    - Remove restriction on size of message.
-   IChannel#get can read a message of any size(before hand it was limited to 
+   IChannel#get can read a message of any size(before hand it was limited to
    1MB in size). Thanks to @quezacoatl.
 
    - IChannel#readable? no longer blocks.
    IChannel#readable? no longer blocks for 0.1 seconds on IO.select call.
-   Thanks to quezacoatl(https://github.com/quezacoatl) for the initial 
-   implementation. 
+   Thanks to quezacoatl(https://github.com/quezacoatl) for the initial
+   implementation.
 
 == v5.0.0
    - Remove IChannel#empty?
-   I think the #readable? method is all you need, and is a much more 
+   I think the #readable? method is all you need, and is a much more
    accurate description of what the method is asking. We cannot determine
-   if the channel is really empty, but we can ask if it is readable at the 
+   if the channel is really empty, but we can ask if it is readable at the
    time you ask.
 
 == v4.1.0
    - Add IChannel#readable?
-   A method that can tell you whether or not a read would block. 
+   A method that can tell you whether or not a read would block.
    When it returns true, a read shouldn't block, on the other hand
    if it were false it'd likely block by the time you call #get.
 == v4.0.0
    - Modify IChannel#empty?
-   It now returns true in case the underlying UNIXSocket being used as a 
+   It now returns true in case the underlying UNIXSocket being used as a
    reader is closed.
 
 == v3.1.0
@@ -80,7 +94,7 @@
    IChannel#empty? returns true when the channel is empty(nothing to read).
 
    - Micro speed improvement on #write!, & #recv! operations.
-   By passing nil instead of creating two empty arrays for every read/write 
+   By passing nil instead of creating two empty arrays for every read/write
    operation we should see a very small improvement in their performance.
 
-   - Add ChangeLog.txt 
+   - Add ChangeLog.txt

data/README.md

@@ -1,44 +1,42 @@
-__OVERVIEW__  
+__OVERVIEW__
 
-| Project         | ichannel   
+| Project         | ichannel
 |:----------------|:--------------------------------------------------
 | Homepage        | https://github.com/robgleeson/ichannel
-| Documentation   | http://rubydoc.info/github/robgleeson/ichannel/frames  
+| Documentation   | http://rubydoc.info/github/robgleeson/ichannel/frames
+| Metrics         | [![Code Climate](https://codeclimate.com/github/robgleeson/ichannel.png)](https://codeclimate.com/github/robgleeson/ichannel)
 | CI              | [![Build Status](https://travis-ci.org/robgleeson/ichannel.png)](https://travis-ci.org/robgleeson/ichannel)
-| Author          | Robert Gleeson             
+| Author          | Robert Gleeson
 
 
 __DESCRIPTION__
 
 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, 
+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](http://www.ruby-doc.org/stdlib-2.0/libdoc/socket/rdoc/UNIXSocket.html) 
-and [redis](https://redis.io). A (unbound) unix socket is local to one machine but it can 
-act as a queue, it has no external dependencies, & it shares the same interface
-as its redis counterpart. A redis channel can do all of the above but also expand 
-its reach beyond one machine by sending and receiving messages from other 
-channels running on different machines. 
-
-A channel depends on a serializer when reading and writing from the underlying 
-transport(i.e: redis or a unix socket) but the choice of serializer is up
-to you. The default is set to be [Marshal](http://ruby-doc.org/core-2.0/Marshal.html) 
-but a serializer can be any object that implements dump and load. A few off the top of
-my head would be JSON, YAML, or MessagePack(with a wrapper, see examples).
+A [unix socket](http://www.ruby-doc.org/stdlib-2.0/libdoc/socket/rdoc/UNIXSocket.html)
+(local to a single machine)  or [redis](https://redis.io) can be used for
+transport.
+
+A channel depends on a serializer when reading and writing from the underlying
+socket(e.g: redis or a unix socket) but you can use any serializer that
+implements the dump and load methods. The default is set to be
+[Marshal](http://ruby-doc.org/core-2.0/Marshal.html)  since it is a core
+ruby module but you could also use JSON, YAML, MessagePack, or <insert your 
+serializer here>.
 
 __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, 
-and a streamed UNIXSocket is mode of transport:
+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,
+and a streamed UNIXSocket is used for transport:
 
 ```ruby
 channel = IChannel.unix Marshal
-pid = fork do 
+pid = fork do
   channel.put Process.pid
   channel.put 'Hello!'
 end
@@ -46,15 +44,28 @@ Process.wait pid
 channel.get # => Fixnum
 channel.get # => 'Hello!'
 ```
-
 __2.__
 
+A demo of a channel sending messages between machines by using
+[redis](https://redis.io) for transport:
+
+```ruby
+channel = IChannel.redis Marshal, host: "10.0.0.1", key: "readme-example"
+channel.put %w(a)
+
+# In another process, on another machine, far away…
+channel = IChannel.redis Marshal, host: "10.0.0.1", key: "readme-example"
+channel.get # => ["a"]
+```
+
+__3.__
+
 Knowing when a channel is readable can be useful so that you can avoid a
-blocking read on the underlying UNIXSocket. This (bad) example demonstrates 
+blocking read on the underlying UNIXSocket. This (bad) example demonstrates
 how to do that:
 
 ```ruby
-channel = IChannel.unix Marshal 
+channel = IChannel.unix Marshal
 pid = fork do
   sleep 3
   channel.put 42
@@ -66,20 +77,6 @@ channel.get # => 42
 Process.wait pid
 ```
 
-__3.__
-
-A demo of a channel sending messages between machines by using
-[redis](https://redis.io) as a backend:
-
-```ruby
-channel = IChannel.redis Marshal, key: "readme-example"
-channel.put %w(a)
-
-# In another process, on another machine, far away…
-channel = IChannel.redis Marshal, key: "readme-example"
-channel.get # => ["a"]
-```
-
 __4.__
 
 MessagePack doesn't implement `dump` or `load` but a wrapper can be easily
@@ -102,18 +99,16 @@ __PLATFORM SUPPORT__
 
 _supported_
 
-  * CRuby (1.9+)  
+  * CRuby (1.9+)
   * Rubinius (1.9+)
   * JRuby (1.9+ - some tests skipped)  
-    JRuby is supported and passes the test suite but it has a few skips.
-    Three skips are because jruby does not implement Kernel.fork and one
-    looks like a possible bug in JRuby's Marshal when trying to deserialize 
-    a channel that uses a unix socket. The other 24 tests pass on jruby, &
-    those tests cover both unix sockets & redis.
+    JRuby is supported and passes the test suite but it has a few skips.  
+    Three skips are because jruby does not implement Kernel.fork.  
+    The other tests pass on jruby, & those tests cover both unix sockets & redis.  
 
 _unsupported_
 
-  * Any 1.8 implementation  
+  * Any 1.8 implementation
   * MacRuby
 
 __INSTALL__
@@ -128,8 +123,8 @@ And to finish:
     $ gem install ichannel
 
 __SEE ALSO__
-  
-  - [ifuture](https://github.com/Havenwood/ifuture)  
+
+  - [ifuture](https://github.com/Havenwood/ifuture)
     futures built on process forks and ichannel.
 
 __LICENSE__

data/ichannel.gemspec

@@ -5,8 +5,7 @@ Gem::Specification.new do |gem|
   gem.version       = IChannel::VERSION
   gem.authors       = ["Robert Gleeson"]
   gem.email         = ["rob@flowof.info"]
-  gem.description   = %q{A modern and easy-to-use interprocess communication 
-    primitive.}
+  gem.description   = %q{interprocess communication channel}
   gem.summary       = gem.description
   gem.homepage      = "https://github.com/robgleeson/ichannel"
 

data/lib/ichannel.rb

@@ -3,8 +3,8 @@ module IChannel
   require_relative "ichannel/unix_socket"
 
   #
-  # @param
-  #   (see UNIXSocket#initialize)
+  # @param 
+  #   (see UNIXSocket#initialize).
   #
   # @return
   #   (see UNIXSocket#initialize)
@@ -24,6 +24,6 @@ module IChannel
     unless defined?(IChannel::Redis)
       require_relative "ichannel/redis"
     end
-    IChannel::Redis.new serializer, options
+    Redis.new serializer, options
   end
 end

data/lib/ichannel/redis.rb

@@ -100,27 +100,26 @@ class IChannel::Redis
 
   #
   # @param [Fixnum] timeout
-  #   The amount of time to wait for the read to complete.
+  #   The number of seconds (as an Integer) to wait before a time out will occur.
   #
   # @raise [IOError]
   #   When the channel is closed or empty.
   #
   # @raise [Timeout::Error]
-  #   When the read does not complete in time.
+  #   When _timeout_ seconds pass and the read has not completed.
   #
   # @return [Object]
   #   The object read from the channel.
   #
-  def recv!(timeout = 0.1)
+  def recv!(timeout = 1)
     if closed?
       raise IOError, 'The channel cannot be read from (closed).'
-    elsif empty?
-      raise IOError, 'The channel cannot be read from (empty).'
+    end
+    _, payload = @redis.brpop @key, timeout
+    if payload
+      @last_msg = @serializer.load(payload)
     else
-      Timeout.timeout(timeout) do
-        dump = @redis.rpop @key
-        @last_msg = @serializer.load dump
-      end
+      raise Timeout::Error, "timeout on read after #{timeout} seconds"
     end
   end
   alias_method :get!, :recv!

data/lib/ichannel/unix_socket.rb

@@ -128,7 +128,7 @@ module IChannel
     # @raise [IOError]
     #   (see IChannel#recv)
     #
-    # @raise [IOError]
+    # @raise [Timeout::Error]
     #   When _timeout_ seconds elapse & the channel remains unreadable.
     #
     # @return [Object]
@@ -143,7 +143,7 @@ module IChannel
         msg = readable[0].readline(SEP).chomp SEP
         @last_msg = @serializer.load msg
       else
-        raise IOError, 'The channel cannot be read from.'
+        raise Timeout::Error, 'Time out on read (waited for %s second(s))' % [timeout]
       end
     end
     alias_method :get!, :recv!
@@ -160,17 +160,5 @@ module IChannel
         !! readable
       end
     end
-
-    # @api private
-    def marshal_load(array)
-      @serializer, reader, writer, @last_msg = array
-      @reader = ::UNIXSocket.for_fd(reader)
-      @writer = ::UNIXSocket.for_fd(writer)
-    end
-
-    # @api private
-    def marshal_dump
-      [@serializer, @reader.to_i, @writer.to_i, @last_msg]
-    end
   end
 end

data/lib/ichannel/version.rb

@@ -1,3 +1,3 @@
 module IChannel
-  VERSION = "6.1.1.1"
+  VERSION = "7.0.0"
 end

data/test/ichannel_redis_test.rb

@@ -12,6 +12,9 @@ class IChannelRedisTest < IChannelUNIXTest
     @channel.close
   end
 
-  def test_serialization() end
-  def test_serialization_in_fork() end
+  def test_timeout_on_get
+    assert_raises Timeout::Error do
+      @channel.get! 1
+    end
+  end
 end

data/test/ichannel_unix_test.rb

@@ -26,31 +26,22 @@ class IChannelUNIXTest < Test::Unit::TestCase
     end
   end
 
-  def test_last_msg_after_read
-    @channel.put [42]
-    @channel.get
-    assert_equal [42], @channel.last_msg
+  def test_blocking_get
+    assert_raises Timeout::Error do
+      Timeout.timeout(1) { @channel.get }
+    end
   end
 
-  def test_serialization_in_fork
-    if RUBY_ENGINE == "jruby"
-      skip "jruby does not implement Kernel.fork"
-    end
-    dump = Marshal.dump(@channel)
-    pid = fork do
-      Marshal.load(dump).put [42]
+  def test_timeout_on_get
+    assert_raises Timeout::Error do
+      @channel.get! 0.1
     end
-    Process.wait pid
-    assert_equal [42], @channel.get
   end
 
-  def test_serialization
-    if RUBY_ENGINE == "jruby"
-      skip "fails on jruby"
-    end
+  def test_last_msg_after_read
     @channel.put [42]
-    dump = Marshal.dump @channel
-    assert_equal [42], Marshal.load(dump).get
+    @channel.get
+    assert_equal [42], @channel.last_msg
   end
 
   def test_fork
@@ -63,7 +54,7 @@ class IChannelUNIXTest < Test::Unit::TestCase
     Process.wait pid
     assert_equal [42], @channel.get
   end
-  
+
   def test_last_msg
     @channel.put %w(a)
     @channel.put %w(b)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ichannel
 version: !ruby/object:Gem::Version
-  version: 6.1.1.1
+  version: 7.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,9 +9,9 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-06 00:00:00.000000000 Z
+date: 2013-07-29 00:00:00.000000000 Z
 dependencies: []
-description: ! "A modern and easy-to-use interprocess communication \n    primitive."
+description: interprocess communication channel
 email:
 - rob@flowof.info
 executables: []
@@ -51,7 +51,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1434889147865179878
+      hash: -3143838182628750731
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -60,13 +60,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1434889147865179878
+      hash: -3143838182628750731
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: A modern and easy-to-use interprocess communication  primitive.
+summary: interprocess communication channel
 test_files:
 - test/ichannel_redis_test.rb
 - test/ichannel_unix_test.rb