Merge pull request #224 from ruby-concurrency/refactor/future-args

Added :args to Future and Promise options hash.

Author: jdantonio

CHANGELOG.md

@@ -1,4 +1,8 @@
-### Next Release v0.7.2 (24 January 2015)
+### Next Release v0.8.0 (25 January 2015)
+
+* Better variable isolation in `Promise` and `Future` via an `:args` option
+
+## Current Release v0.7.2 (24 January 2015)
 
 * New `Semaphore` class based on [java.util.concurrent.Semaphore](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Semaphore.html)
 * New `Promise.all?` and `Promise.any?` class methods
@@ -15,7 +19,7 @@
 * Tests now run on new Travis build environment
 * Multiple documentation updates
 
-## Current Release v0.7.1 (4 December 2014)
+### Release v0.7.1 (4 December 2014)
 
 Please see the [roadmap](https://github.com/ruby-concurrency/concurrent-ruby/issues/142) for more information on the next planned release.
 

lib/concurrent/future.rb

@@ -23,6 +23,8 @@ class Future < IVar
     #   global task pool (for short-running tasks)
     # @option opts [object] :executor when provided will run all operations on
     #   this executor rather than the global thread pool (overrides :operation)
+    # @option opts [object, Array] :args zero or more arguments to be passed the task block on execution
+    #
     # @option opts [String] :dup_on_deref (false) call `#dup` before returning the data
     # @option opts [String] :freeze_on_deref (false) call `#freeze` before returning the data
     # @option opts [String] :copy_on_deref (nil) call the given `Proc` passing the internal value and
@@ -35,6 +37,7 @@ def initialize(opts = {}, &block)
       @state = :unscheduled
       @task = block
       @executor = OptionsParser::get_executor_from(opts) || Concurrent.configuration.global_operation_pool
+      @args = OptionsParser::get_arguments_from(opts)
     end
 
     # Execute an `:unscheduled` `Future`. Immediately sets the state to `:pending` and
@@ -52,11 +55,9 @@ def initialize(opts = {}, &block)
     # @example Instance and execute in one line
     #   future = Concurrent::Future.new{ sleep(1); 42 }.execute
     #   future.state #=> :pending
-    #
-    # @since 0.5.0
     def execute
       if compare_and_set_state(:pending, :unscheduled)
-        @executor.post{ work }
+        @executor.post(@args){ work }
         self
       end
     end
@@ -72,6 +73,8 @@ def execute
     #   global task pool (for short-running tasks)
     # @option opts [object] :executor when provided will run all operations on
     #   this executor rather than the global thread pool (overrides :operation)
+    # @option opts [object, Array] :args zero or more arguments to be passed the task block on execution
+    #
     # @option opts [String] :dup_on_deref (false) call `#dup` before returning the data
     # @option opts [String] :freeze_on_deref (false) call `#freeze` before returning the data
     # @option opts [String] :copy_on_deref (nil) call the given `Proc` passing the internal value and
@@ -84,8 +87,6 @@ def execute
     # @example
     #   future = Concurrent::Future.execute{ sleep(1); 42 }
     #   future.state #=> :pending
-    #
-    # @since 0.5.0
     def self.execute(opts = {}, &block)
       Future.new(opts, &block).execute
     end
@@ -96,7 +97,7 @@ def self.execute(opts = {}, &block)
 
     # @!visibility private
     def work # :nodoc:
-      success, val, reason = SafeTaskExecutor.new(@task).execute
+      success, val, reason = SafeTaskExecutor.new(@task).execute(*@args)
       complete(success, val, reason)
     end
   end

lib/concurrent/options_parser.rb

@@ -23,6 +23,10 @@ def get_executor_from(opts = {})
       end
     end
 
+    def get_arguments_from(opts = {})
+      [*opts.fetch(:args, [])]
+    end
+
     # Get the requested `Executor` based on the values set in the options hash.
     #
     # @param [Hash] opts the options defining the requested executor

lib/concurrent/promise.rb

@@ -172,29 +172,34 @@ class Promise
 
     # Initialize a new Promise with the provided options.
     #
-    # @param [Hash] opts the options used to define the behavior at update and deref
+    # @!macro [attach] promise_init_options
     #
-    # @option opts [Promise] :parent the parent `Promise` when building a chain/tree
-    # @option opts [Proc] :on_fulfill fulfillment handler
-    # @option opts [Proc] :on_reject rejection handler
+    #   @param [Hash] opts the options used to define the behavior at update and deref
     #
-    # @option opts [Boolean] :operation (false) when `true` will execute the future on the global
-    #   operation pool (for long-running operations), when `false` will execute the future on the
-    #   global task pool (for short-running tasks)
-    # @option opts [object] :executor when provided will run all operations on
-    #   this executor rather than the global thread pool (overrides :operation)
+    #   @option opts [Promise] :parent the parent `Promise` when building a chain/tree
+    #   @option opts [Proc] :on_fulfill fulfillment handler
+    #   @option opts [Proc] :on_reject rejection handler
     #
-    # @option opts [String] :dup_on_deref (false) call `#dup` before returning the data
-    # @option opts [String] :freeze_on_deref (false) call `#freeze` before returning the data
-    # @option opts [String] :copy_on_deref (nil) call the given `Proc` passing the internal value and
-    #   returning the value returned from the proc
+    #   @option opts [Boolean] :operation (false) when `true` will execute the future on the global
+    #     operation pool (for long-running operations), when `false` will execute the future on the
+    #     global task pool (for short-running tasks)
+    #   @option opts [object] :executor when provided will run all operations on
+    #     this executor rather than the global thread pool (overrides :operation)
+    #   @option opts [object, Array] :args zero or more arguments to be passed the task block on execution
+    #
+    #   @option opts [String] :dup_on_deref (false) call `#dup` before returning the data
+    #   @option opts [String] :freeze_on_deref (false) call `#freeze` before returning the data
+    #   @option opts [String] :copy_on_deref (nil) call the given `Proc` passing the internal value and
+    #     returning the value returned from the proc
     #
     # @see http://wiki.commonjs.org/wiki/Promises/A
     # @see http://promises-aplus.github.io/promises-spec/
     def initialize(opts = {}, &block)
       opts.delete_if { |k, v| v.nil? }
 
       @executor = OptionsParser::get_executor_from(opts) || Concurrent.configuration.global_operation_pool
+      @args = OptionsParser::get_arguments_from(opts)
+
       @parent = opts.fetch(:parent) { nil }
       @on_fulfill = opts.fetch(:on_fulfill) { Proc.new { |result| result } }
       @on_reject = opts.fetch(:on_reject) { Proc.new { |reason| raise reason } }
@@ -219,7 +224,6 @@ def self.reject(reason, opts = {})
     end
 
     # @return [Promise]
-    # @since 0.5.0
     def execute
       if root?
         if compare_and_set_state(:pending, :unscheduled)
@@ -232,7 +236,18 @@ def execute
       self
     end
 
-    # @since 0.5.0
+    # Create a new `Promise` object with the given block, execute it, and return the
+    # `:pending` object.
+    #
+    # @!macro promise_init_options
+    #
+    # @return [Promise] the newly created `Promise` in the `:pending` state
+    #
+    # @raise [ArgumentError] if no block is given
+    #
+    # @example
+    #   promise = Concurrent::Promise.execute{ sleep(1); 42 }
+    #   promise.state #=> :pending
     def self.execute(opts = {}, &block)
       new(opts, &block).execute
     end
@@ -389,6 +404,7 @@ def self.aggregate(method, *promises)
       composite
     end
 
+    # @!visibility private
     def set_pending
       mutex.synchronize do
         @state = :pending
@@ -413,6 +429,7 @@ def on_reject(reason)
       nil
     end
 
+    # @!visibility private
     def notify_child(child)
       if_state(:fulfilled) { child.on_fulfill(apply_deref_options(@value)) }
       if_state(:rejected) { child.on_reject(@reason) }
@@ -421,7 +438,7 @@ def notify_child(child)
     # @!visibility private
     def realize(task)
       @executor.post do
-        success, value, reason = SafeTaskExecutor.new(task).execute
+        success, value, reason = SafeTaskExecutor.new(task).execute(*@args)
 
         children_to_notify = mutex.synchronize do
           set_state!(success, value, reason)
@@ -432,11 +449,13 @@ def realize(task)
       end
     end
 
+    # @!visibility private
     def set_state!(success, value, reason)
       set_state(success, value, reason)
       event.set
     end
 
+    # @!visibility private
     def synchronized_set_state!(success, value, reason)
       mutex.lock
       set_state!(success, value, reason)

spec/concurrent/future_spec.rb

@@ -2,6 +2,7 @@
 require_relative 'dereferenceable_shared'
 require_relative 'obligation_shared'
 require_relative 'observable_shared'
+require_relative 'thread_arguments_shared'
 
 module Concurrent
 
@@ -18,6 +19,18 @@ module Concurrent
 
     context 'behavior' do
 
+      # thread_arguments
+
+      def get_ivar_from_no_args
+        Concurrent::Future.execute{|*args| args }
+      end
+
+      def get_ivar_from_args(opts)
+        Concurrent::Future.execute(opts){|*args| args }
+      end
+
+      it_should_behave_like :thread_arguments
+
       # obligation
 
       let!(:fulfilled_value) { 10 }

spec/concurrent/options_parser_spec.rb

@@ -9,6 +9,50 @@ module Concurrent
     let(:task_pool){ ImmediateExecutor.new }
     let(:operation_pool){ ImmediateExecutor.new }
 
+    context '#get_arguments_from' do
+
+      it 'returns an empty array when opts is not given' do
+        args = OptionsParser::get_arguments_from
+        expect(args).to be_a Array
+        expect(args).to be_empty
+      end
+
+      it 'returns an empty array when opts is an empty hash' do
+        args = OptionsParser::get_arguments_from({})
+        expect(args).to be_a Array
+        expect(args).to be_empty
+      end
+
+      it 'returns an empty array when there is no :args key' do
+        args = OptionsParser::get_arguments_from(foo: 'bar')
+        expect(args).to be_a Array
+        expect(args).to be_empty
+      end
+
+      it 'returns an empty array when the :args key has a nil value' do
+        args = OptionsParser::get_arguments_from(args: nil)
+        expect(args).to be_a Array
+        expect(args).to be_empty
+      end
+
+      it 'returns a one-element array when the :args key has a non-array value' do
+        args = OptionsParser::get_arguments_from(args: 'foo')
+        expect(args).to eq ['foo']
+      end
+
+      it 'returns an array when when the :args key has an array value' do
+        expected = [1, 2, 3, 4]
+        args = OptionsParser::get_arguments_from(args: expected)
+        expect(args).to eq expected
+      end
+
+      it 'returns the given array when the :args key has a complex array value' do
+        expected = [(1..10).to_a, (20..30).to_a, (100..110).to_a]
+        args = OptionsParser::get_arguments_from(args: expected)
+        expect(args).to eq expected
+      end
+    end
+
     context '#get_executor_from' do
 
       it 'returns the given :executor' do

spec/concurrent/promise_spec.rb

@@ -1,5 +1,6 @@
 require 'spec_helper'
 require_relative 'obligation_shared'
+require_relative 'thread_arguments_shared'
 
 module Concurrent
 
@@ -23,7 +24,24 @@ module Concurrent
       Promise.reject(rejected_reason, executor: executor)
     end
 
-    it_should_behave_like :obligation
+    context 'behavior' do
+
+      # thread_arguments
+
+      def get_ivar_from_no_args
+        Concurrent::Promise.execute{|*args| args }
+      end
+
+      def get_ivar_from_args(opts)
+        Concurrent::Promise.execute(opts){|*args| args }
+      end
+
+      it_should_behave_like :thread_arguments
+
+      # obligation
+
+      it_should_behave_like :obligation
+    end
 
     it 'includes Dereferenceable' do
       promise = Promise.new{ nil }

spec/concurrent/thread_arguments_shared.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+
+shared_examples :thread_arguments do
+
+  it 'passes an empty array when opts is not given' do
+    future = get_ivar_from_no_args
+    expect(future.value).to eq []
+  end
+
+  it 'passes an empty array when opts is an empty hash' do
+    future = get_ivar_from_args({})
+    expect(future.value).to eq []
+  end
+
+  it 'passes an empty array when there is no :args key' do
+    future = get_ivar_from_args(foo: 'bar')
+    expect(future.value).to eq []
+  end
+
+  it 'passes an empty array when the :args key has a nil value' do
+    future = get_ivar_from_args(args: nil)
+    expect(future.value).to eq []
+  end
+
+  it 'passes a one-element array when the :args key has a non-array value' do
+    future = get_ivar_from_args(args: 'foo')
+    expect(future.value).to eq ['foo']
+  end
+
+  it 'passes an array when when the :args key has an array value' do
+    expected = [1, 2, 3, 4]
+    future = get_ivar_from_args(args: expected)
+    expect(future.value).to eq expected
+  end
+
+  it 'passes the given array when the :args key has a complex array value' do
+    expected = [(1..10).to_a, (20..30).to_a, (100..110).to_a]
+    future = get_ivar_from_args(args: expected)
+    expect(future.value).to eq expected
+  end
+
+  it 'allows the given arguments array to be dereferenced' do
+    expected = [1, 2, 3, 4]
+    future = get_ivar_from_args(args: expected)
+    expect(future.value).to eq expected
+  end
+end