ichannel 1.0.0 → 2.0.0

data/README.md

@@ -11,12 +11,14 @@ __OVERVIEW__
 
 __DESCRIPTION__
 
-Provides a modern and easy to use interprocess communication(IPC) primitive.
-It can be used to transport Ruby objects between Ruby processes running on the 
-same machine. The serialization options are flexible: any serializer that 
-implements `#dump` & `#load` can be used -- this covers Marshal, YAML, & JSON 
-out of the box but not MsgPack -- although you could easily write a wrapper 
-around msgpack.
+A modern, flexible & easy to use interprocess communication(IPC) primitive. The 
+basic premise is that you can "put" and "get" Ruby objects to/from a channel. 
+This works across any Ruby process & its subprocesses, though, which is why it 
+can be useful. You could describe putting and getting objects to/from the channel
+as message passing but the message could potentially be any Ruby object, 
+although I think sending small messages(as a Hash) works very well for most 
+scenarios. You have the potential to serialize any object that `Marshal` can 
+dump+load, though.
 
 __EXAMPLES__
 
@@ -26,14 +28,43 @@ The first example shows off how you'd pass Ruby objects through a channel.
 The serializer of choice is `Marshal` but it could just as easily be `JSON` or
 `YAML`.
 
-    channel = IChannel.new Marshal
-    channel.put 'hello'
-    channel.put 'goodbye'
-    pid = fork do 
-      channel.get # => 'hello'
-      channel.get # => 'goodbye'
-    end
-    Process.wait pid
+```ruby
+channel = IChannel.new Marshal
+pid = fork do 
+  channel.put Process.pid
+  channel.put 'Hello!'
+end
+Process.wait pid
+channel.get # => Fixnum
+channel.get # => 'Hello!'
+```
+
+__SERIALIZERS__
+
+To send Ruby objects between processes they have to be serialized, but on the
+bright side the number of serializers to choose from is vast. Marshal, JSON, & 
+YAML are supported out of the box to name a few but adding support for other 
+serializers is a trivial amount of work.
+
+For example, here is a MessagePack serializer you could use:
+
+```ruby
+require 'ichannel'
+require 'msgpack'
+serializer = Class.new do
+  def self.dump(msg)
+    MessagePack.pack msg
+  end
+
+  def self.load(msg)
+    MessagePack.unpack msg
+  end
+end
+channel = IChannel.new serializer
+```
+
+As you can see above as long as the serializer responds to `.dump` & `.load` it 
+can be passed as a serializer to IChannel.
 
 __REAL WORLD EXAMPLES__
  

data/ichannel.gemspec

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

data/lib/ichannel.rb

@@ -9,34 +9,33 @@ class IChannel
     @serializer = serializer 
   end
 
-  #
-  # Close the channel.
-  #
-  # @return [void]
-  #
-  def close
-    [@reader.close,@writer.close]
-  end
-
   #
   # @return [Boolean]
-  #   Returns true if the channel is closed.
+  #   Returns true when the channel is closed.
   #
   def closed?
     @reader.closed? && @writer.closed?
   end
 
+  #
+  # Close the channel.
   #
   # @return [Boolean]
-  #   Returns true if the channel is open.
+  #   Returns true when the channel has been closed.
+  #   Returns nil when the channel is already closed.
   #
-  def open?
-    !closed?
+  def close
+    if !@reader.closed? && !@writer.closed?
+      !! [@reader.close, @writer.close]
+    end
   end
 
   #
   # Add an object to the channel.
   #
+  # @raise [IOError]
+  #   When the channel cannot be written to.
+  #
   # @param [Object] object
   #   An object to add to the channel.
   #
@@ -44,6 +43,8 @@ class IChannel
     _, writable, _ = IO.select [], [@writer], [], 0.1
     if writable
       @writer.send @serializer.dump(object), 0
+    else
+      raise IOError, 'The channel cannot be written to.'
     end
   end
   alias_method :put, :write
@@ -51,6 +52,9 @@ class IChannel
   #
   # Receive a object from the channel.
   #
+  # @raise [IOError]
+  #   When the channel cannot be read from.
+  #
   # @return [Object]
   #   The object added to the channel.
   #
@@ -59,6 +63,8 @@ class IChannel
     if readable
       msg, _ = @reader.recvmsg
       @serializer.load msg
+    else
+      raise IOError, 'The channel cannot be read from.' 
     end
   end
   alias_method :get, :recv

data/lib/ichannel/version.rb

@@ -1,3 +1,3 @@
 class IChannel
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end

data/test/ichannel_class_test.rb

@@ -16,6 +16,20 @@ class IChannelTest < Test::Unit::TestCase
     assert_equal %w(a b c), @channel.get
   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.put %w(b)
+    end
+  end
+
   def test_queued_messages
     pid = fork do 
       @channel.put %w(a)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ichannel
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,9 +9,9 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-15 00:00:00.000000000 Z
+date: 2012-11-17 00:00:00.000000000 Z
 dependencies: []
-description: ! "A simple and modern interprocess communication \n    primitive."
+description: ! "A modern and easy-to-use interprocess communication \n    primitive."
 email:
 - rob@flowof.info
 executables: []
@@ -43,7 +43,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3802321299613243923
+      hash: -795267943345486764
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -52,13 +52,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3802321299613243923
+      hash: -795267943345486764
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: A simple and modern interprocess communication  primitive.
+summary: A modern and easy-to-use interprocess communication  primitive.
 test_files:
 - test/ichannel_class_test.rb
 - test/setup.rb