object-channel 0.1.3

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in object-channel.gemspec
+gemspec

data/LICENSE.md

@@ -0,0 +1,18 @@
+Copyright (c) 2012 [Simply Measured](http://simplymeasured.com/)
+
+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,105 @@
+Object Channel
+==============
+
+In some testing scenarios (such as signal handling), it is helpful to be able to test 
+from outside a process; common methods for communicating between two ends of a fork 
+include pushing data to an intermediary, such as a database or filesystem, but both 
+have side-effects: additional dependencies (many of which have their own dependencies) 
+and/or the need for post-run cleanup.
+
+To avoid this, I often use IO.pipe:
+
+```ruby
+reader,writer = IO.pipe
+
+child_pid = fork do
+  reader.close
+  writer.write( "Hello, I'm #{Process.pid}" )
+  writer.close
+end
+writer.close
+
+message_from_child = reader.read
+reader.close
+
+puts Process.pid          # => 12338
+puts child_pid            # => 12345
+puts message_from_child   # => "Hello, I'm 12345"
+``` 
+
+But that has several drawbacks:
+
+ - `read` only works if all `write` ends of the pipe are
+   closed; keeping track of which is open and which is closed
+   is a pain, especially if you have to fork several layers deep.
+ - only a single message can be passed; multiple messages 
+   adds complexity, and complicated test cases aren't a good
+   idea
+ - only strings can be passed; sure Objects can be serialized, but...
+
+
+A Simpler Way
+------------
+
+Adding this kind of logic directly into your tests is a bad idea; it makes them 
+unnecessarily complicated, hard to read, and easy to get wrong. `ObjectChannel` 
+abstracts all that away so you can just test. Here's the same simple example, but 
+this time without all the pipe-closing: 
+
+```ruby
+require 'object-channel'
+
+p2c = ObjectChannel.fork do |c2p|
+  c2p.transmit( "Hello, I'm #{Process.pid}" )
+end
+
+puts Process.pid          # => 12338
+puts p2c.pid              # => 12345
+puts p2c.receive!         # => "Hello, I'm 12345"
+```
+
+Features
+--------
+
+`ObjectChannel` provides the following features:
+
+ - Full-fledged objects, not just strings
+ - Bi-directional channel
+ - Blocking and non-blocking access
+ - block-invoke supported and fully optional
+ - No additional dependencies
+ - No cleanup necessary
+
+Check out the [specs][] for examples.
+
+License & Contributing
+======================
+
+Project is (c) 2012 [Simply Measured][simply-measured] and released under an 
+[MIT-style license][license]
+
+* This project uses Vincent Driessen's [Git-Flow][git-flow] branching model. 
+* Check out the latest develop to make sure the feature hasn't been implemented 
+  or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it 
+  and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a 
+  future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to 
+  have your own version, or is otherwise necessary, that is fine, but please 
+  isolate to its own commit so I can cherry-pick around it.
+
+
+<!-- INTERNAL LINKS -->
+
+[license]: https://github.com/simplymeasured/object-channel/blob/master/LICENSE.md
+[specs]: https://github.com/simplymeasured/object-channel/blob/master/spec/
+
+<!-- EXTERNAL LINKS -->
+
+[simply-measured]: http://simplymeasured.com/
+[git-flow]: http://nvie.com/posts/a-successful-git-branching-model/
+

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end

data/lib/object-channel.rb

@@ -0,0 +1,228 @@
+# require "object-channel/version"
+
+class ObjectChannel
+  class << self
+    ##
+    # Create object channels endpoints, each connected by an object channel. 
+    #
+    def create(endpoints=2)
+      endpoints.times.to_a.map do |index|
+        pipe = IO.pipe
+        {:index=>index, :pipe=>pipe}
+      end.permutation(2).to_a.inject(Hash.new{|h,k|h[k]=Hash.new}) do |channels,pipes|
+        from = pipes[0]
+        to = pipes[1]
+        channels[from[:index]][to[:index]] = ObjectChannel.new( from[:pipe], to[:pipe] )
+        channels
+      end
+    end
+
+    # :nodoc: 
+    def new(receive_pipe,transmit_pipe)
+      object_channel = allocate
+      [
+      :@receive_reader,
+      :@receive_writer,
+      :@transmit_reader,
+      :@transmit_writer
+      ].zip([receive_pipe,transmit_pipe].flatten(1)) do |name,ios|
+        object_channel.instance_variable_set(name,ios)
+      end
+      object_channel
+    end
+
+    ## 
+    # Creates a subprocess with a bi-directional ObjectChannel
+    # available to both processes, behaving otherwise like Process.fork.
+    # 
+    # If a block is specified, the block is run in the subprocess with
+    # the ObjectChannel::Pair to its parent as its only argument. Like 
+    # Process.fork(), the subprocess terminates with a status of zero.
+    # 
+    # Otherwise, the fork call returns twice, once in the parent, returning
+    # the ObjectChannel to its child whose pid method is the process ID 
+    # of that child, and once in the child, returning the ObjectChannel to 
+    # the parent, whose pid method returns nil.
+    # 
+    # :call-seq:
+    #   ObjectChannel.fork -> ObjectChannel x 2
+    #   ObjectChannel.fork{|channel|} -> ObjectChannel
+    # 
+    # = Example (Block)
+    #   
+    #     p2c = ObjectChannel.fork do |c2p|
+    #       c2p.transmit :foo => :bar
+    #       puts "child received <#{p2c.receive!.inspect}>" #=> [1, 2, 3]
+    #     end
+    #     puts "parent received <#{p2c.receive!.inspect}>" #=> {:foo=>:bar}
+    #     channel.transmit [1,2,3]
+    # 
+    # = Example (No Block)
+    #   
+    #     if (channel = ObjectChannel.fork).pid
+    #       channel.transmit :foo => :bar
+    #       puts "child received <#{channel.receive!.inspect}>" #=> [1, 2, 3]
+    #     else
+    #       puts "received <#{channel.receive!.inspect}>" #=> {:foo=>:bar}
+    #       channel.transmit [1,2,3]
+    #       exit
+    #     end
+    # 
+    def fork name=nil, &block
+      channels = create(2)
+      channel_a = channels[0][1]
+      channel_b = channels[1][0]
+
+      if block_given?
+        ret = fork name
+        if ret.nil? or (ret.respond_to?(:pid) and ret.pid.nil?)
+          begin
+            block.call(*(ret.respond_to?(:pid) ? [ret] : [] ) )
+          ensure
+            exit!
+          end
+        end
+        return ret
+      else
+        pid = forker.fork
+        channel = ( pid.nil? ? channel_a : channel_b)
+        if name.nil?
+          channel.instance_variable_set(:@pid, pid)
+          channel
+        else
+          Object.const_set name, channel
+          pid
+        end
+      end
+    end
+
+    ##
+    # Allows the object that forks to be replaced, helpful for adding additional
+    # functionality in something of a daisy-chain.
+    # 
+    # The forker's fork method *must* be API-compatible with Kernel.fork:
+    #   - It *must* work with and without blocks provided
+    #   - It *must* return an integer pid to the parent and nil to the child
+    #   - It *must not* require any arguments, as args are swallowed in ObjectChannel.fork()
+    # 
+    attr_writer :forker
+    def forker
+      (@forker || ::Kernel)
+    end
+  end
+
+  attr_reader :pid
+
+  ##
+  # Transmit an object
+  #
+  def transmit(object)
+    close(:@transmit_reader)
+    @transmit_writer.write [Marshal.dump(object)].pack('m').gsub("\n",'') + "\n"
+  end
+
+  ##
+  # Receive the next object in a blocking manner
+  # 
+  def receive!
+    close(:@receive_writer)
+    begin
+      r = @receive_reader.readline
+      Marshal.load(r.unpack("m")[0])
+    rescue EOFError
+      return nil
+    end
+  end
+
+  ##
+  # Receive the next object in a non-blocking manner
+  # Returns nil if no object was present
+  def receive
+    receive! if ready?
+  end
+
+  ##
+  # Test to see if there is anything to receive 
+  #
+  def ready?
+    c = Thread.start{@receive_reader.getc}
+    Thread.pass
+    if c.status == false and c.value
+      @receive_reader.ungetc(c.value)
+      return true
+    else
+      c.kill
+      return false
+    end
+  end
+
+  ##
+  # Test to see if the receive_reader is at eof in a non-blocking manner
+  # 
+  def closed?
+    c = Thread.start{@receive_reader.eof?}
+    Thread.pass
+    if c.status == false and c.value
+      return true
+    else
+      c.kill
+      return false
+    end
+  end
+
+  ##
+  # Close all ends of all IOS.
+  #
+  def close!
+    [
+      :@receive_reader,
+      :@receive_writer,
+      :@transmit_reader,
+      :@transmit_writer
+    ].each &method(:close)
+  end
+
+  ##
+  # Close an IO by name
+  # 
+  def close(ios_name)
+    ios = instance_variable_get(ios_name)
+    ios.close unless ios.closed?
+  end
+end
+
+## 
+# A Bonus Example:
+#
+# a proc that both call
+#   pingpong = Proc.new do |channel, action|
+#     srand(Process.pid)
+#     def report(message) puts %Q{#{Process.pid}: #{message}}; end
+#     begin
+#       break (report 'VICTORY!') if channel.closed? or !(received = channel.receive!)
+#       report "got #{received}"
+      
+#       break (report 'aw, man!') if Kernel.rand(99) > 61
+#       report "returning <#{action}>"
+#       channel.transmit(action)
+#     end while true
+#     channel.close!
+#   end
+
+# # without a block
+#   if (channel = ObjectChannel.fork).pid
+#     pingpong.call(channel, 'ping!')
+#     Process.wait(channel.pid)
+#   else
+#     channel.transmit('serve!')
+#     pingpong.call(channel, 'pong.')
+#     exit
+#   end
+
+# # with a block
+#   channel = ObjectChannel.fork do |channel| 
+#     pingpong.call(channel,'ping!')
+#   end 
+#   channel.transmit 'SERVICE!'
+#   pingpong.call(channel,'pong.')
+#   Process.wait(channel.pid)

data/lib/object-channel/version.rb

@@ -0,0 +1,3 @@
+class ObjectChannel
+    VERSION = "0.1.3"
+end

data/object-channel.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "object-channel/version"
+
+Gem::Specification.new do |s|
+  s.name        = "object-channel"
+  s.version     = ObjectChannel::VERSION
+  s.authors     = ["Ryan Biesemeyer"]
+  s.email       = ["ryan@yaauie.com"]
+  s.homepage    = "https://github.com/simplymeasured/object-channel"
+  s.summary     = %q{A library for sending objects over pipes, with convenience methods for forking}
+  s.description = %q{Wraps around Process.fork(), providing parent and child each an ObjectChannel to transmit objects to and receive objects from the other.}
+
+  #s.rubyforge_project = "object-channel"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'bundler'
+end

data/spec/object-channel_spec.rb

@@ -0,0 +1,165 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe 'ObjectChannel' do
+  module CustomForker
+    extend self
+    def fork(*a,&b)
+      $FORKER = "#{self.to_s}.fork"
+      ::Kernel.fork(*a,&b)
+    end
+  end
+
+  [nil,CustomForker].each do |forker|
+    before(:each) do
+      ObjectChannel.forker = forker
+    end
+    after(:each) do
+      ObjectChannel.forker = forker
+      $FORKER = nil
+    end
+    describe '#fork' do
+      it 'should be able to send an object for processing' do
+        channel = ObjectChannel.fork do |channel|
+          received = channel.receive!
+          channel.transmit( received + 1 )
+        end
+        channel.transmit 100
+        channel.receive!.should == 101
+      end
+
+      it 'should actually happen on a separate process' do
+        def prepend_pid(s); "#{Process.pid}: #{s}"; end
+        channel = ObjectChannel.fork do |channel|
+          received = channel.receive!
+          channel.transmit prepend_pid(received)
+        end
+        channel.transmit 'foobar'
+        channel.receive!.should_not == prepend_pid('foobar')
+      end
+
+      context 'with constantized channels' do
+        after(:each){ Object.send(:remove_const, :NamedChannel) }
+        it 'should be able to use the constantized channels' do
+          ObjectChannel.fork :NamedChannel do
+            received = NamedChannel.receive!
+            NamedChannel.transmit received.reverse
+          end
+          NamedChannel.transmit 'foobar'
+          NamedChannel.receive!.should == 'raboof'
+          NamedChannel.close!
+        end
+      end
+
+      describe 'block-invoke' do
+        after(:each){ Object.send(:remove_const, :OuterChannel) }
+        # OK, I have to do some tricky magic here.
+        # If you know of a better way, by all means, reimplement.
+        it 'should invoke exit! when done' do
+          if (ObjectChannel.fork :OuterChannel)
+            begin
+              ObjectChannel.fork :InnerChannel do
+                InnerChannel.receive!
+              end
+              InnerChannel.transmit 'foo' #get the party started
+            rescue SystemExit => exception
+              OuterChannel.transmit exception
+              raise exception
+            end
+            exit! 0
+          else
+            output = OuterChannel.receive!
+            output.should be_nil
+            output.inspect.should_not == '#<SystemExit: exit>'
+            OuterChannel.receive!.should be_nil # it shouldn't invoke exit twice!
+          end
+        end
+
+        it 'should run the block in the child' do
+          cached_pid = Process.pid
+          ObjectChannel.fork(:OuterChannel){exit!}
+          Process.pid.should == cached_pid
+        end
+      end
+
+      unless forker.nil?
+        context 'with a custom forker' do
+          context 'ObjectChannel.forker' do
+            subject{ ObjectChannel.forker }
+            it{ should_not be_nil }
+          end
+          context 'when run' do
+            before(:each) do
+              ObjectChannel.fork(:NamedChannel){ $RAN=true }
+            end
+            after(:each){ Object.send(:remove_const, :NamedChannel) }
+            subject{ $FORKER }
+            it 'should have run in the custom forker' do
+              should == "#{forker.to_s}.fork"
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+
+# Bonus example:
+# An Isolater. It'll run the supplied block in a child process, 
+# then appropriately return or raise the result in the parent process.
+# Note: It does not currently support catch/throw, so it's possible to bypass.
+describe 'isolate' do
+  module Isolater
+    extend self
+    def isolate( &block )
+      p2c = ObjectChannel.fork do |c2p|
+        begin
+          c2p.transmit( [:returned, block.call] )
+        rescue Object => obj_raised
+          c2p.transmit( [:raised, obj_raised] )
+        end
+      end
+      verb, value = p2c.receive!
+
+      raise value if verb == :raised
+      return value if verb == :returned
+
+      raise RuntimeError, 'expected something to be returned or raised; got <#{verb},#{value}>'
+    end
+    def dirty?
+      !!(@dirty)
+    end
+    attr_writer :dirty
+  end
+
+  it 'should be isolated' do
+    Isolater.dirty = false
+    Isolater.isolate do
+      Isolater.dirty = true
+    end
+    Isolater.dirty?.should be_false
+  end
+
+  context 'when block returns' do
+    subject do
+      lambda{ return { :k=>'value', :int=>4 } }
+    end
+
+    it 'should not raise' do
+      expect{ Isolater.isolate{ subject.call } }.to_not raise_exception
+    end
+    it 'should return the correct value' do
+      subject.call.should == { :k=>'value', :int=>4 }
+    end
+  end
+
+  context 'when block raises' do
+    subject do
+      lambda{ $GLOBAL_VALUE = true; 5 / 0 }
+    end
+
+    it 'should raise' do
+      expect{ Isolater.isolate{ subject.call } }.to raise_exception(ZeroDivisionError)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'object-channel'
+
+

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification 
+name: object-channel
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 3
+  version: 0.1.3
+platform: ruby
+authors: 
+- Ryan Biesemeyer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-03-19 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: Wraps around Process.fork(), providing parent and child each an ObjectChannel to transmit objects to and receive objects from the other.
+email: 
+- ryan@yaauie.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE.md
+- README.md
+- Rakefile
+- lib/object-channel.rb
+- lib/object-channel/version.rb
+- object-channel.gemspec
+- spec/object-channel_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/simplymeasured/object-channel
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A library for sending objects over pipes, with convenience methods for forking
+test_files: 
+- spec/object-channel_spec.rb
+- spec/spec_helper.rb