dataflow 0.3.0 → 0.3.1

data/README.textile

@@ -58,6 +58,20 @@ local do |x, y, z|
 end
 </pre>
 
+<pre>
+# Module methods version
+ 
+Dataflow.local do |x, y, z|
+  # notice how the order automatically gets resolved
+  Thread.new { Dataflow.unify y, x + 2 }
+  Thread.new { Dataflow.unify z, y + 3 }
+  Thread.new { Dataflow.unify x, 1 }
+  z #=> 6
+end
+
+# Note that a gobal Dataflow.declare is not supported
+</pre>
+
 <pre>
 # Instance variables
 class AnimalHouse
@@ -118,6 +132,91 @@ local do |x, y, z|
 end        
 </pre>
 
+<pre>
+include Dataflow
+
+# flow without parameters
+local do |x|
+  flow do 
+    # other stuff
+    unify x, 1337
+  end
+  x #=> 1337
+end
+
+# flow with an output parameter
+local do |x|
+  flow(x) do
+    # other stuff
+    1337
+  end
+  x #=> 1337
+end
+</pre>
+
+<pre>
+# barrier
+include Dataflow
+
+local do |lock1, lock2|
+  flow { unify lock1, :unlocked }
+  flow { unify lock2, :unlocked }
+  barrier lock1, lock2
+  puts "Barrier broken!"  
+end
+</pre>
+
+<pre>
+# FutureQueue
+include Dataflow
+
+local do |queue, first, second|
+  unify queue, Dataflow::FutureQueue.new
+  queue.pop first
+  queue.push 1
+  queue.push 2
+  queue.pop second
+  first #=> 1
+  second #=> 2
+end
+</pre>
+
+h1. Anonymous variables
+
+Sometimes you may want to pack a data structure with variables that do not need to be referenced with labels. For those cases anonymous variables are a good choice, here are some options:
+
+<pre>
+include Dataflow
+Array.new(3) { Dataflow::Variable.new }
+Array.new(3) { Dataflow.local }
+Array.new(3) { local }
+# and technically not anonymous
+Array.new(3) { local {|v| v } }
+</pre>
+
+h1. Debugging
+
+If you are having trouble and need to debug dataflow variables, simply call #inspect.
+
+If the variable has already been bound, it call inspect on its bound value like normal.However, if the variable is not bound yet then you will get a special string that contains the proxies #__id__ that you can use to track down which proxy objects are being passed around to which parts of your program:
+<pre>
+include Dataflow
+local do |my_var| 
+  my_var.inspect # => #<Dataflow::Variable:2637860 unbound> 
+end
+</pre>
+
+h1. Fork method customization
+
+By default both #flow and #need_later use Thread.fork as their fork method. Youc an access the fork method via Dataflow.forker.
+
+If you would like to use a custom forker, simple set it to an object that responds to #call and internally calls a block passed to it (for an example of a synchronous forker, see spec/forker_spec.rb):
+<pre>
+Dataflow.forker = MyClass.method(:fork_with_threadpool)
+</pre>
+
+Also note that #flow is used interally by #need_later, in case you want to override that specifically.
+
 h1. Ports using Dataflow
 
 Ports are an extension of the declarative concurrent model to support nondeterministic behavior. They accomplish this through the use of a single state variable. Ports are also inspired by the Oz language.

data/dataflow.rb

@@ -1,7 +1,11 @@
 require 'monitor'
 
 module Dataflow
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
+  class << self
+    attr_accessor :forker
+  end
+  self.forker = Thread.method(:fork)
   
   def self.included(cls)
     class << cls
@@ -19,6 +23,7 @@ module Dataflow
   end
   
   def local(&block)
+    return Variable.new unless block_given?
     vars = Array.new(block.arity) { Variable.new }
     block.call *vars
   end
@@ -36,7 +41,7 @@ module Dataflow
   end
 
   def flow(output=nil, &block)
-    Thread.new do
+    Dataflow.forker.call do
       result = block.call
       unify output, result if output
     end
@@ -44,7 +49,7 @@ module Dataflow
 
   def need_later(&block)
     local do |future|
-      flow { unify future, block.call }
+      flow(future) { block.call }
       future
     end
   end

data/examples/barrier.rb

@@ -0,0 +1,9 @@
+require "#{File.dirname(__FILE__)}/../dataflow"
+include Dataflow
+
+local do |lock1, lock2|
+  flow { unify lock1, :unlocked }
+  flow { unify lock2, :unlocked }
+  barrier lock1, lock2
+  puts "Barrier broken!"  
+end

data/examples/flow.rb

@@ -0,0 +1,20 @@
+require "#{File.dirname(__FILE__)}/../dataflow"
+include Dataflow
+
+# flow without parameters
+local do |x|
+  flow do 
+    # other stuff
+    unify x, 1337
+  end
+  puts x
+end
+
+# flow with an output parameter
+local do |x|
+  flow(x) do
+    # other stuff
+    1337
+  end
+  puts x
+end

data/examples/future_queue.rb

@@ -0,0 +1,11 @@
+require "#{File.dirname(__FILE__)}/../dataflow"
+include Dataflow
+
+local do |queue, first, second|
+  unify queue, Dataflow::FutureQueue.new
+  queue.pop first
+  queue.push 1
+  queue.push 2
+  queue.pop second
+  puts "first:  #{first}, second: #{second}"
+end

data/spec/anonymous_variables_spec.rb

@@ -0,0 +1,21 @@
+require "#{File.dirname(__FILE__)}/spec_helper"
+
+describe 'Using an anonymous variable' do
+  it 'works with Variable instances' do
+    container = [Dataflow::Variable.new]
+    unify container.first, 1337
+    container.first.should == 1337
+  end
+
+  it 'works with Dataflow.local' do
+    container = [Dataflow.local]
+    unify container.first, 1337
+    container.first.should == 1337
+  end
+
+  it 'works with #local' do
+    container = [local]
+    unify container.first, 1337
+    container.first.should == 1337
+  end
+end

data/spec/forker_spec.rb

@@ -0,0 +1,28 @@
+require "#{File.dirname(__FILE__)}/spec_helper"
+
+describe 'Setting a customer forker' do
+  before(:all) do
+    @original_forker = Dataflow.forker
+    Dataflow.forker = Class.new do
+      def self.synchronous_forker(&block)
+        block.call
+      end
+    end.method(:synchronous_forker)
+  end
+
+  after(:all) do
+    Dataflow.forker = @original_forker
+  end
+  
+  it 'uses the custom forker in #flow' do
+    local do |my_var|
+      flow(my_var) { 1337 }
+      my_var.should == 1337
+    end
+  end
+
+  it 'uses the custom forker in #need_later' do
+    my_var = need_later { 1337 }
+    my_var.should == 1337
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: dataflow
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors: 
 - Larry Diehl
@@ -31,9 +31,12 @@ files:
 - dataflow/equality.rb
 - dataflow/future_queue.rb
 - dataflow/port.rb
+- examples/barrier.rb
 - examples/data_driven.rb
 - examples/dataflow_http_gets.rb
+- examples/flow.rb
 - examples/future_http_gets.rb
+- examples/future_queue.rb
 - examples/instance_variables.rb
 - examples/laziness.rb
 - examples/local_variables.rb
@@ -69,11 +72,13 @@ specification_version: 2
 summary: Dataflow concurrency for Ruby (inspired by the Oz language)
 test_files: 
 - spec/actor_spec.rb
+- spec/anonymous_variables_spec.rb
 - spec/barrier_spec.rb
 - spec/by_need_spec.rb
 - spec/dataflow_spec.rb
 - spec/equality_spec.rb
 - spec/flow_spec.rb
+- spec/forker_spec.rb
 - spec/future_queue_spec.rb
 - spec/inspect_spec.rb
 - spec/need_later_spec.rb