barney 0.7.0 → 0.8.0

data/ChangeLog

@@ -1,3 +1,12 @@
+2011-04-19  Robert Gleeson <rob@flowof.info> v0.8.0
+
+* Remove "seq" attribute from StreamPair.
+* Banish @seq.
+* Add HistoryItem (subclass of Struct).
+* Share#history returns an Array of HistoryItem objects.
+* Share#shared is deprecated. Use Shared#variables instead.
+
+
 2011-03-14  Robert Gleeson <rob@flowof.info> v0.7.0
 
 * Barney::Share#initialize yields a block.  

data/README.md

@@ -1,87 +1,58 @@
  ![Barney Picture](http://ompldr.org/vNnUwNA)
 
 Barney tries to make the sharing of data between processes as easy and **natural** as possible.  
-Barney is developed against Ruby 1.9.1 or later. I'm not knowingly supporting earlier versions of Ruby.
+Barney is developed to run on Ruby 1.9.1 or later, but it may work on earlier versions of Ruby as well.
 
-## Sharable objects
-Behind the scenes, Barney is using Marshal to send data between processes.  
-Any object that can be dumped through Marshal.dump can be shared.  
-This excludes anonymous modules, anonymous classes, Proc objects, and possibly some other objects I
-cannot think of.
+## Limitations
 
-## Thread safety
+* Sharable objects  
+  Behind the scenes, Barney is using Marshal to send data between processes.  
+  Any object that can be dumped through Marshal.dump can be shared.  
+  This excludes anonymous modules, anonymous classes, Proc objects, and possibly some other objects I
+  cannot think of.
 
-Barney is thread-safe as long as one instance of Barney::Share is used per-thread.  
-There is a mutex lock in place, but it only concerns Barney::Share#synchronize, where data is shared
-among all instances of Barney::Share.
+* Thread safety  
+  Barney is thread-safe as long as one instance of Barney::Share is used per-thread.  
+  There is a mutex lock in place, but it only concerns Barney::Share#synchronize, where data is shared
+  among all instances of Barney::Share.
 
 ## Examples
 
-Okay, now that we've got that out of the way, let's see what using Barney is like.
+Okay, now that we've got that out of the way, let's see what using Barney is like:  
+(The [Samples](https://github.com/robgleeson/barney/tree/develop/samples) directory has more examples …)
 
 **Basic**
 
       #!/usr/bin/env ruby
       require 'barney'
 
-      message = 'foo'
-      $times  = 2
 
       obj = Barney::Share.new
-      obj.share :message, :$times    
+      obj.share :message
+      message = 'Hello, '
+
       pid = obj.fork do 
-        message.sub! 'f', 'b'
-        $times += 1
+        message << 'World!'
       end
 
       Process.wait pid
       obj.sync
       
-      puts message * $times # output is 'boobooboo'.
- 
-**Sequential Jobs**
-      
-      #!/usr/bin/env ruby
-      require 'barney'
-
-      a = "12"
-
-      obj = Barney::Share.new
-      obj.share :a
-
-      3.upto(4).each do |i|
-        pid = obj.fork { a << i.to_s }
-        Process.wait pid
-        obj.sync
-      end
-
-      a # => "1234"
-
-**Paralell Jobs**
-
-      #/usr/bin/env ruby
-      require 'barney'
-
-      results = {}
-      pids    = []
+      puts message # 'Hello, World!' 
 
-      obj = Barney::Share.new
-      obj.share :results
 
-      [1,2,3].each do |e|
-        pids << obj.fork do 
-          results.merge!(e => e)
-        end
-      end
+## Install
 
-      pids.each { |pid| Process.wait pid }
-      obj.sync
+RubyGems.org
+      gem install barney
 
-      obj.history.each_value do |history| 
-        results.merge! history[:results]
-      end
+Github
+      git clone git://github.com/robgleeson/barney.git
+      cd barney
+      gem build *.gemspec
+      gem install *.gem
 
-      puts results.inspect # => { 1 => 1, 2 => 2, 3 => 3 }
+I'm following the [Semantic Versioning](http://www.semver.org) policy.  
 
 ## Documentation
 
@@ -95,13 +66,9 @@ Okay, now that we've got that out of the way, let's see what using Barney is lik
 * [0.4.0](http://rubydoc.info/gems/barney/0.4.0)
 * …
 
+
 ## License
 
 Barney is released under the Lesser GPL(LGPL).  
 
-## Install
-
-      gem install barney
 
-The repository has a gemspec you can build and install from, too.
-I'm following the [Semantic Versioning](http://www.semver.org) policy.

data/lib/barney/share.rb

@@ -2,21 +2,24 @@ module Barney
 
   class Share
 
-    # @attr [Fixnum] seq The associated sequence number. 
     # @attr [IO] in      The pipe which is used to read data.       
     # @attr [IO] out     The pipe which is used to write data.
     # @api private
-    StreamPair = Struct.new :seq, :in, :out
+    StreamPair = Struct.new :in, :out
+
+    # @attr [Symbol] variable The variable name.
+    # @attr [Object] value    The value of the variable.
+    HistoryItem = Struct.new :variable, :value
 
     @mutex = Mutex.new
 
     class << self
-      # Serves as a temporary holder for the latest value read from the child process.
+      # Returns the latest value read from a spawned child process. 
       # @api private
-      # @return [Object] Returns Object or subclass of.
+      # @return [Object]
       attr_accessor :value
 
-      # Serves as a lock when {Barney::Share.value Barney::Share.value} is being accessed by {Barney::Share#synchronize}
+      # Returns a Mutex that is used when {Barney::Share.value Barney::Share.value} is being accessed by {Barney::Share#synchronize}
       # @api private
       # @return [Mutex] 
       attr_reader :mutex
@@ -24,23 +27,22 @@ module Barney
 
     # Returns a list of all variables or constants being shared for this instance of {Barney::Share Barney::Share}.
     # @return [Array<Symbol>] 
-    attr_reader :shared
-    def shared; @shared.keys; end
-  
-    # Serves as a method that tells you the Process ID of the last forked child process.
-    # @return [Fixnum] Returns the Process ID as a Fixnum.
+    attr_reader :variables
+
+    # Returns the Process ID of the last forked process.
+    # @return [Fixnum]
     attr_reader :pid
 
-    # Serves as a method to provide a history of changes made in multiple forks for a single instance of {Barney::Share}.
-    # @return [{ Fixnum => { Symbol => Object }}] Fixnum represents sequence, Symbol the variable, and Object its value. 
+    # @return [Array<HistoryItem>]
     attr_reader :history
     
-    # @return [Barney::Share] Returns an instance of Barney::Share.
+    # @yieldparam [Barney::Share] self Yields an instance of {Barney::Share}.
+    # @return [Barney::Share]
     def initialize
-      @shared  = {}
-      @history = {}
-      @context = nil
-      @seq     = 0
+      @shared    = Hash.new { |h,k| h[k] = [] }
+      @variables = []
+      @history   = []
+      @context   = nil
       yield self if block_given? 
     end
 
@@ -48,22 +50,15 @@ module Barney
     # @param  [Symbol] Variable   Accepts a variable amount of Symbol objects.
     # @return [Array<Symbol>]     Returns a list of all variables that are being shared.
     def share *variables
-      variables.map(&:to_sym).each do |variable|
-        if (@shared[variable].nil?) || (not @shared[variable].find { |struct| struct.seq == @seq })
-          @shared.store variable, (@shared[variable] || []) << StreamPair.new(@seq, *IO.pipe)
-        end
-      end
-      @shared.keys
+      @variables.push *variables.map(&:to_sym)
     end
 
     # Serves as a method to remove a variable or constant from being shared between two processes.
     # @param  [Symbol] Variable Accepts a variable amount of Symbol objects.
     # @return [Array<Symbol>]   Returns a list of the variables that are still being shared.
     def unshare *variables
-      variables.map(&:to_sym).each do |variable|
-        @shared.delete variable
-      end
-      @shared.keys
+      variables.map(&:to_sym).each { |variable| @variables.delete variable }
+      @variables
     end
 
     # Serves as a method to spawn a new child process.  
@@ -77,20 +72,19 @@ module Barney
     # @return [Fixnum]        Returns the Process ID(PID) of the spawned child process.  
     def fork &blk
       raise ArgumentError, "A block or Proc object is expected" unless block_given?
-      share *@shared.keys if @pid
+      spawn_pipes
 
       @context = blk.binding
       @pid     = Kernel.fork do
         blk.call
-        @shared.each do |variable, array|
-          stream = array[-1]
+        @shared.each do |variable, history|
+          stream = history[-1]
           stream.in.close  
           stream.out.write Marshal.dump(eval("#{variable}", @context))
           stream.out.close
         end
       end
-      
-      @seq += 1
+
       @pid
     end
 
@@ -99,20 +93,31 @@ module Barney
     # @return [void]
     def synchronize 
       Barney::Share.mutex.synchronize do
-        @shared.each do |variable, array|
-          array.each do |stream|
+        @shared.each do |variable, history|
+          history.each do |stream|
             stream.out.close
             Barney::Share.value = Marshal.load stream.in.read
             stream.in.close
-            object = eval "#{variable} = Barney::Share.value", @context 
-            @history[stream.seq] = (@history[stream.seq] || {}).merge!({ variable => object })
+            value = eval "#{variable} = Barney::Share.value", @context 
+            @history.push HistoryItem.new variable.to_sym, value
           end
-          array.clear
         end
       end
     end
     alias_method :sync, :synchronize
 
+    private
+
+    def spawn_pipes
+      @shared.keep_if do |variable|
+        @variables.member? variable
+      end
+
+      @variables.each do |variable|
+        @shared[variable].push StreamPair.new *IO.pipe
+      end
+    end
+
   end
 
 end

data/lib/barney.rb

@@ -1,6 +1,6 @@
 require 'barney/share' 
 
 module Barney 
-  VERSION = '0.7.0'
+  VERSION = '0.8.0'
 end
 

data/test/suite/lib/barney/share#history.rb

@@ -1,19 +1,21 @@
 describe Barney::Share do
   describe '#history' do
 
-    it 'should confirm #history provides the correct history' do
-      hash = {}
-      expected = { 0 => { :hash => { 1 => 1 } }, 1 => { :hash => { 2 => 2 } }, 2 => { :hash => { 3 => 3 } } }
+    it 'should provide the correct history.' do     
       object = Barney::Share.new
-      object.share :hash
+      object.share :shared
+      shared = ""
 
-      [1,2,3].each do |e|
-        pid = object.fork { hash.merge! e => e }
+      %w(a b c).each do |e|
+        pid = object.fork { shared << e }
         Process.wait pid
       end
 
       object.sync
-      assert_equal expected, object.history
+
+      history = object.history
+      assert_equal true, history.all? { |item| item.variable == :shared }
+      assert_equal "abc", history.map { |item| item.value }.join 
     end
 
   end

data/test/suite/lib/barney/share#initialize.rb

@@ -2,7 +2,9 @@ describe Barney::Share do
   describe '#initialize' do
   
     it 'should take a block' do
-      Barney::Share.new { |obj| }
+      actual = false
+      Barney::Share.new { |obj| actual = true }
+      assert_equal true, actual
     end
 
   end

data/test/suite/lib/barney/share#synchronize.rb

@@ -51,22 +51,31 @@ describe Barney::Share do
     end
 
     it 'should fix Github Issue #2' do
-      a,b = 4,5
-      @object.share :a
+      x = 4
+      y = 5
+
+      @object.share :x
       @object.fork { }
       Process.wait @object.pid
-      @object.share :b 
+
+      @object.share :y 
       @object.fork { b = 6 }
+      Process.wait @object.pid
+
       @object.sync # will raise NoMethodError if fails. 
     end
 
     it 'should fix GitHub Issue #3' do
-      a,b = 4,5
-      @object.share :a, :b
+      x = 4
+      y = 5
+
+      @object.share :x, :y
       @object.fork { }
       Process.wait @object.pid
       @object.sync
-      assert_equal({ 0 => { :a => 4, :b => 5 } }, @object.history)
+
+      assert_equal 4, @object.history[0].value
+      assert_equal 5, @object.history[1].value
     end
 
   end

data/test/suite/lib/barney/share#unshare.rb

@@ -16,10 +16,10 @@ describe Barney::Share do
       assert_equal 5, @a
     end
     
-    it 'should confirm a shared variable is removed from #shared.' do
+    it 'should confirm a shared variable is removed from #variables.' do
       @object.share :@a
       @object.unshare :@a
-      assert_equal true, @object.shared.empty?
+      assert_equal true, @object.variables.empty?
     end
 
  end

metadata

@@ -2,7 +2,7 @@
 name: barney
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors: 
 - Robert Gleeson
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-14 00:00:00 +00:00
+date: 2011-04-19 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -55,7 +55,6 @@ files:
 - test/suite/lib/barney/share#fork.rb
 - test/suite/lib/barney/share#history.rb
 - test/suite/lib/barney/share#initialize.rb
-- test/suite/lib/barney/share#shared.rb
 - test/suite/lib/barney/share#synchronize.rb
 - test/suite/lib/barney/share#unshare.rb
 has_rdoc: true
@@ -90,6 +89,5 @@ test_files:
 - test/suite/lib/barney/share#fork.rb
 - test/suite/lib/barney/share#history.rb
 - test/suite/lib/barney/share#initialize.rb
-- test/suite/lib/barney/share#shared.rb
 - test/suite/lib/barney/share#synchronize.rb
 - test/suite/lib/barney/share#unshare.rb

data/test/suite/lib/barney/share#shared.rb

@@ -1,11 +0,0 @@
-describe Barney::Share do
-  describe '#shared' do
-
-    it 'should return a list of shared variables' do 
-      obj = Barney::Share.new
-      obj.share :a, :b, :c
-      assert_equal true, [:a, :b, :c].all? { |variable| obj.shared.include? variable }
-    end
-
-  end
-end