concurrent-ruby 0.7.0.rc2-java → 0.7.1-java

data/lib/concurrent/executor/serialized_execution.rb

@@ -1,12 +1,14 @@
 require 'delegate'
 require 'concurrent/executor/executor'
 require 'concurrent/logging'
+require 'concurrent/atomic/synchronization'
 
 module Concurrent
 
   # Ensures passed jobs in a serialized order never running at the same time.
   class SerializedExecution
     include Logging
+    include Synchronization
 
     Job = Struct.new(:executor, :args, :block) do
       def call
@@ -15,9 +17,10 @@ module Concurrent
     end
 
     def initialize
-      @being_executed = false
-      @stash          = []
-      @mutex          = Mutex.new
+      synchronize do
+        @being_executed = false
+        @stash          = []
+      end
     end
 
     # Submit a task to the executor for asynchronous processing.
@@ -33,23 +36,36 @@ module Concurrent
     #
     # @raise [ArgumentError] if no task is given
     def post(executor, *args, &task)
-      return nil if task.nil?
-
-      job = Job.new executor, args, task
-
-      begin
-        @mutex.lock
-        post = if @being_executed
-                 @stash << job
-                 false
-               else
-                 @being_executed = true
-               end
-      ensure
-        @mutex.unlock
+      posts [[executor, args, task]]
+      true
+    end
+
+    # As {#post} but allows to submit multiple tasks at once, it's guaranteed that they will not
+    # be interleaved by other tasks.
+    #
+    # @param [Array<Array(Executor, Array<Object>, Proc)>] posts array of triplets where
+    #   first is a {Executor}, second is array of args for task, third is a task (Proc)
+    def posts(posts)
+      # if can_overflow?
+      #   raise ArgumentError, 'SerializedExecution does not support thread-pools which can overflow'
+      # end
+
+      return nil if posts.empty?
+
+      jobs = posts.map { |executor, args, task| Job.new executor, args, task }
+
+      job_to_post = synchronize do
+        if @being_executed
+          @stash.push(*jobs)
+          nil
+        else
+          @being_executed = true
+          @stash.push(*jobs[1..-1])
+          jobs.first
+        end
       end
 
-      call_job job if post
+      call_job job_to_post if job_to_post
       true
     end
 
@@ -78,11 +94,8 @@ module Concurrent
     def work(job)
       job.call
     ensure
-      begin
-        @mutex.lock
+      synchronize do
         job = @stash.shift || (@being_executed = false)
-      ensure
-        @mutex.unlock
       end
 
       call_job job if job
@@ -98,7 +111,7 @@ module Concurrent
     include SerialExecutor
 
     def initialize(executor)
-      @executor = executor
+      @executor   = executor
       @serializer = SerializedExecution.new
       super(executor)
     end

data/lib/concurrent/executor/thread_pool_executor.rb

@@ -49,6 +49,8 @@ module Concurrent
     #   * `:discard`: Silently discard the task and return `nil` as the task result.
     #   * `:caller_runs`: Execute the task on the calling thread.
     #
+    #   {include:file:doc/thread_pools.md}
+    #
     #   @note When running on the JVM (JRuby) this class will inherit from `JavaThreadPoolExecutor`.
     #     On all other platforms it will inherit from `RubyThreadPoolExecutor`.
     #

data/lib/concurrent/executor/timer_set.rb

@@ -22,10 +22,10 @@ module Concurrent
     # @option opts [object] :executor when provided will run all operations on
     #   this executor rather than the global thread pool (overrides :operation)
     def initialize(opts = {})
-      @queue = PriorityQueue.new(order: :min)
-      @task_executor = OptionsParser::get_executor_from(opts) || Concurrent.configuration.global_task_pool
+      @queue          = PriorityQueue.new(order: :min)
+      @task_executor  = OptionsParser::get_executor_from(opts) || Concurrent.configuration.global_task_pool
       @timer_executor = SingleThreadExecutor.new
-      @condition = Condition.new
+      @condition      = Condition.new
       init_executor
     end
 
@@ -64,7 +64,7 @@ module Concurrent
     # For a timer, #kill is like an orderly shutdown, except we need to manually
     # (and destructively) clear the queue first
     def kill
-      @queue.clear
+      mutex.synchronize { @queue.clear }
       shutdown
     end
 
@@ -124,14 +124,13 @@ module Concurrent
     # @!visibility private
     def process_tasks
       loop do
-        break if @queue.empty?
-
-        task = @queue.peek
+        task = mutex.synchronize { @queue.peek }
+        break unless task
         interval = task.time - Time.now.to_f
 
         if interval <= 0
           @task_executor.post(*task.args, &task.op)
-          @queue.pop
+          mutex.synchronize { @queue.pop }
         else
           mutex.synchronize do
             @condition.wait(mutex, [interval, 60].min)

data/lib/concurrent/executors.rb

@@ -1,6 +1,7 @@
 require 'concurrent/executor/cached_thread_pool'
 require 'concurrent/executor/fixed_thread_pool'
 require 'concurrent/executor/immediate_executor'
+require 'concurrent/executor/indirect_immediate_executor'
 require 'concurrent/executor/per_thread_executor'
 require 'concurrent/executor/safe_task_executor'
 require 'concurrent/executor/single_thread_executor'

data/lib/concurrent/future.rb

@@ -6,35 +6,7 @@ require 'concurrent/executor/safe_task_executor'
 
 module Concurrent
 
-  # A `Future` represents a promise to complete an action at some time in the future.
-  # The action is atomic and permanent. The idea behind a future is to send an operation
-  # for asynchronous completion, do other stuff, then return and retrieve the result
-  # of the async operation at a later time.
-  #
-  # A `Future` has four possible states: *:unscheduled*, *:pending*, *:rejected*, or *:fulfilled*.
-  # When a `Future` is created its state is set to *:unscheduled*. Once the `#execute` method is
-  # called the state becomes *:pending* and will remain in that state until processing is
-  # complete. A completed `Future` is either *:rejected*, indicating that an exception was
-  # thrown during processing, or *:fulfilled*, indicating success. If a `Future` is *:fulfilled*
-  # its `value` will be updated to reflect the result of the operation. If *:rejected* the
-  # `reason` will be updated with a reference to the thrown exception. The predicate methods
-  # `#unscheduled?`, `#pending?`, `#rejected?`, and `fulfilled?` can be called at any time to
-  # obtain the state of the `Future`, as can the `#state` method, which returns a symbol. 
-  #
-  # Retrieving the value of a `Future` is done through the `#value` (alias: `#deref`) method.
-  # Obtaining the value of a `Future` is a potentially blocking operation. When a `Future` is
-  # *:rejected* a call to `#value` will return `nil` immediately. When a `Future` is
-  # *:fulfilled* a call to `#value` will immediately return the current value. When a
-  # `Future` is *:pending* a call to `#value` will block until the `Future` is either
-  # *:rejected* or *:fulfilled*. A *timeout* value can be passed to `#value` to limit how
-  # long the call will block. If `nil` the call will block indefinitely. If `0` the call will
-  # not block. Any other integer or float value will indicate the maximum number of seconds to block.
-  #
-  # The `Future` class also includes the behavior of the Ruby standard library `Observable` module,
-  # but does so in a thread-safe way. On fulfillment or rejection all observers will be notified
-  # according to the normal `Observable` behavior. The observer callback function will be called
-  # with three parameters: the `Time` of fulfillment/rejection, the final `value`, and the final
-  # `reason`. Observers added after fulfillment/rejection will still be notified as normal.
+  # {include:file:doc/future.md}
   #
   # @see http://ruby-doc.org/stdlib-2.1.1/libdoc/observer/rdoc/Observable.html Ruby Observable module
   # @see http://clojuredocs.org/clojure_core/clojure.core/future Clojure's future function
@@ -94,6 +66,12 @@ module Concurrent
     #
     # @yield the asynchronous operation to perform
     #
+    # @param [Hash] opts the options controlling how the future will be processed
+    # @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 [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

data/lib/concurrent/ivar.rb

@@ -6,6 +6,10 @@ require 'concurrent/observable'
 
 module Concurrent
 
+  # An `IVar` is like a future that you can assign. As a future is a value that is being computed that you can wait on, an `IVar` is a value that is waiting to be assigned, that you can wait on. `IVars` are single assignment and deterministic.
+  # 
+  # Then, express futures as an asynchronous computation that assigns an `IVar`. The `IVar` becomes the primitive on which [futures](Future) and [dataflow](Dataflow) are built.
+  #
   # An `IVar` is a single-element container that is normally created empty, and
   # can only be set once. The I in `IVar` stands for immutable. Reading an `IVar`
   # normally blocks until it is set. It is safe to set and read an `IVar` from
@@ -15,6 +19,11 @@ module Concurrent
   # a `Future`. If you want to create a graph of parallel tasks all executed when
   # the values they depend on are ready you want `dataflow`. `IVar` is generally
   # a low-level primitive.
+  # 
+  # **See Also:**
+  #
+  # * For the theory: Arvind, R. Nikhil, and K. Pingali. [I-Structures: Data structures for parallel computing](http://dl.acm.org/citation.cfm?id=69562). In Proceedings of Workshop on Graph Reduction, 1986.
+  # * For recent application: [DataDrivenFuture in Habanero Java from Rice](http://www.cs.rice.edu/~vs3/hjlib/doc/edu/rice/hj/api/HjDataDrivenFuture.html).
   #
   # @example Create, set and get an `IVar`
   #   ivar = Concurrent::IVar.new

data/lib/concurrent/logging.rb

@@ -12,6 +12,9 @@ module Concurrent
     # @yieldreturn [String] a message
     def log(level, progname, message = nil, &block)
       (@logger || Concurrent.configuration.logger).call level, progname, message, &block
+    rescue => error
+      $stderr.puts "`Concurrent.configuration.logger` failed to log #{[level, progname, message, block]}\n" +
+          "#{error.message} (#{error.class})\n#{error.backtrace.join "\n"}"
     end
   end
 end

data/lib/concurrent/mvar.rb

@@ -4,16 +4,33 @@ require 'concurrent/atomic/event'
 
 module Concurrent
 
-  # An `MVar` is a single-element container that blocks on `get` if it is empty,
-  # and blocks on `put` if it is full. It is safe to use an `MVar` from
-  # multiple threads. `MVar` can be seen as a single-element blocking queue, or
-  # a rendezvous variable.
+  # An `MVar` is a synchronized single element container. They are empty or contain one item.
+  # Taking a value from an empty `MVar` blocks, as does putting a value into a full one.
+  # You can either think of them as blocking queue of length one, or a special kind of
+  # mutable variable. 
+  # 
+  # On top of the fundamental `#put` and `#take` operations, we also provide a `#mutate`
+  # that is atomic with respect to operations on the same instance. These operations all
+  # support timeouts. 
+  # 
+  # We also support non-blocking operations `#try_put!` and `#try_take!`, a `#set!` that
+  # ignores existing values, a `#value` that returns the value without removing it or
+  # returns `MVar::EMPTY`, and a `#modify!` that yields `MVar::EMPTY` if the `MVar` is
+  # empty and can be used to set `MVar::EMPTY`. You shouldn't use these operations in the
+  # first instance. 
+  # 
+  # `MVar` is a [Dereferenceable](Dereferenceable).
+  # 
+  # `MVar` is related to M-structures in Id, `MVar` in Haskell and `SyncVar` in Scala.
   #
-  # An `MVar` is typically used to transfer objects between threads, where the
-  # sending thread will block if the previous message hasn't been taken yet by the
-  # receiving thread. It can also be used to control access to some global shared
-  # state, where threads `take` the value, perform some operation, and then
-  # `put` it back.
+  # Note that unlike the original Haskell paper, our `#take` is blocking. This is how
+  # Haskell and Scala do it today.
+  # 
+  # **See Also:**
+  # 
+  # 1. P. Barth, R. Nikhil, and Arvind. [M-Structures: Extending a parallel, non-
+  # strict, functional language with state](http://dl.acm.org/citation.cfm?id=652538). In Proceedings of the 5th ACM Conference on Functional Programming Languages and Computer Architecture (FPCA), 1991.
+  # 2. S. Peyton Jones, A. Gordon, and S. Finne. [Concurrent Haskell](http://dl.acm.org/citation.cfm?id=237794). In Proceedings of the 23rd Symposium on Principles of Programming Languages (PoPL), 1996.
   class MVar
 
     include Dereferenceable

data/lib/concurrent/observable.rb

@@ -3,6 +3,39 @@ require 'concurrent/atomic/copy_on_write_observer_set'
 
 module Concurrent
 
+  # The [observer pattern](http://en.wikipedia.org/wiki/Observer_pattern) is one of the most useful design pattern.
+  # 
+  # The workflow is very simple:
+  # - an `observer` can register itself to a `subject` via a callback
+  # - many `observers` can be registered to the same `subject`
+  # - the `subject` notifies all registered observers when its status changes
+  # - an `observer` can deregister itself when is no more interested to receive event notifications
+  # 
+  # In a single threaded environment the whole pattern is very easy: the `subject` can use a simple data structure to manage all its subscribed `observer`s and every `observer` can react directly to every event without caring about synchronization.
+  # 
+  # In a multi threaded environment things are more complex.
+  # The `subject` must synchronize the access to its data structure and to do so currently we're using two specialized ObserverSet: CopyOnWriteObserverSet and CopyOnNotifyObserverSet.
+  # 
+  # When implementing and `observer` there's a very important rule to remember: **there are no guarantees about the thread that will execute the callback**
+  # 
+  # Let's take this example
+  # ```
+  # class Observer
+  #   def initialize
+  #     @count = 0
+  #   end
+  # 
+  #   def update
+  #     @count += 1
+  #   end
+  # end
+  # 
+  # obs = Observer.new
+  # [obj1, obj2, obj3, obj4].each { |o| o.add_observer(obs) }
+  # # execute [obj1, obj2, obj3, obj4]
+  # ```
+  # 
+  # `obs` is wrong because the variable `@count` can be accessed by different threads at the same time, so it should be synchronized (using either a Mutex or an AtomicFixum)
   module Observable
 
     # @return [Object] the added observer

data/lib/concurrent/promise.rb

@@ -5,8 +5,9 @@ require 'concurrent/options_parser'
 
 module Concurrent
 
-  # TODO unify promise and future to single class, with dataflow
+  # {include:file:doc/promise.md}
   class Promise
+    # TODO unify promise and future to single class, with dataflow
     include Obligation
 
     # Initialize a new Promise with the provided options.
@@ -110,6 +111,63 @@ module Concurrent
     alias_method :catch, :rescue
     alias_method :on_error, :rescue
 
+    # Yield the successful result to the block that returns a promise. If that
+    # promise is also successful the result is the result of the yielded promise.
+    # If either part fails the whole also fails.
+    #
+    # @example
+    #   Promise.execute { 1 }.flat_map { |v| Promise.execute { v + 2 } }.value! #=> 3
+    #
+    # @return [Promise]
+    def flat_map(&block)
+      child = Promise.new(
+        parent: self,
+        executor: ImmediateExecutor.new,
+      )
+
+      on_error { |e| child.on_reject(e) }
+      on_success do |result1|
+        begin
+          inner = block.call(result1)
+          inner.execute
+          inner.on_success { |result2| child.on_fulfill(result2) }
+          inner.on_error { |e| child.on_reject(e) }
+        rescue => e
+          child.on_reject(e)
+        end
+      end
+
+      child
+    end
+
+    # Builds a promise that produces the result of promises in an Array
+    # and fails if any of them fails.
+    #
+    # @param [Array<Promise>] promises
+    #
+    # @return [Promise<Array>]
+    def self.zip(*promises)
+      zero = fulfill([], executor: ImmediateExecutor.new)
+
+      promises.reduce(zero) do |p1, p2|
+        p1.flat_map do |results|
+          p2.then do |next_result|
+            results << next_result
+          end
+        end
+      end
+    end
+
+    # Builds a promise that produces the result of self and others in an Array
+    # and fails if any of them fails.
+    #
+    # @param [Array<Promise>] others
+    #
+    # @return [Promise<Array>]
+    def zip(*others)
+      self.class.zip(self, *others)
+    end
+
     protected
 
     def set_pending

data/lib/concurrent/scheduled_task.rb

@@ -4,6 +4,7 @@ require 'concurrent/executor/safe_task_executor'
 
 module Concurrent
 
+  # {include:file:doc/scheduled_task.md}
   class ScheduledTask < IVar
 
     attr_reader :schedule_time

data/lib/concurrent/timer_task.rb

@@ -10,7 +10,7 @@ module Concurrent
   # intervals. The thread that performs the task sleeps for the given interval then
   # wakes up and performs the task. Lather, rinse, repeat... This pattern causes two
   # problems. First, it is difficult to test the business logic of the task because the
-  # task itself is tightly coupled with the concurrency logic. Second, an exception in
+  # task itself is tightly coupled with the concurrency logic. Second, an exception
   # raised while performing the task can cause the entire thread to abend. In a
   # long-running application where the task thread is intended to run for days/weeks/years
   # a crashed task thread can pose a significant problem. `TimerTask` alleviates both problems.
@@ -23,13 +23,13 @@ module Concurrent
   # performing logging or ancillary operations. `TimerTask` can also be configured with a
   # timeout value allowing it to kill a task that runs too long.
   # 
-  # One other advantage of `TimerTask` is it forces the business logic to be completely decoupled
+  # One other advantage of `TimerTask` is that it forces the business logic to be completely decoupled
   # from the concurrency logic. The business logic can be tested separately then passed to the
   # `TimerTask` for scheduling and running.
   # 
   # In some cases it may be necessary for a `TimerTask` to affect its own execution cycle.
-  # To facilitate this a reference to the task object is passed into the block as a block
-  # argument every time the task is executed.
+  # To facilitate this, a reference to the TimerTask instance is passed as an argument
+  # to the provided block every time the task is executed.
   # 
   # The `TimerTask` class includes the `Dereferenceable` mixin module so the result of
   # the last execution is always available via the `#value` method. Derefencing options
@@ -39,13 +39,13 @@ module Concurrent
   # `TimerTask` supports notification through the Ruby standard library
   # {http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html Observable}
   # module. On execution the `TimerTask` will notify the observers
-  # with threes arguments: time of execution, the result of the block (or nil on failure),
+  # with three arguments: time of execution, the result of the block (or nil on failure),
   # and any raised exceptions (or nil on success). If the timeout interval is exceeded
   # the observer will receive a `Concurrent::TimeoutError` object as the third argument.
   #
   # @example Basic usage
   #   task = Concurrent::TimerTask.new{ puts 'Boom!' }
-  #   task.run!
+  #   task.execute
   #   
   #   task.execution_interval #=> 60 (default)
   #   task.timeout_interval   #=> 30 (default)
@@ -53,7 +53,7 @@ module Concurrent
   #   # wait 60 seconds...
   #   #=> 'Boom!'
   #   
-  #   task.stop #=> true
+  #   task.shutdown #=> true
   #
   # @example Configuring `:execution_interval` and `:timeout_interval`
   #   task = Concurrent::TimerTask.new(execution_interval: 5, timeout_interval: 5) do
@@ -65,7 +65,7 @@ module Concurrent
   #
   # @example Immediate execution with `:run_now`
   #   task = Concurrent::TimerTask.new(run_now: true){ puts 'Boom!' }
-  #   task.run!
+  #   task.execute
   #   
   #   #=> 'Boom!'
   #
@@ -75,7 +75,7 @@ module Concurrent
   #     execution_interval: 5
   #   ){ Time.now }
   #   
-  #   task.run!
+  #   task.execute
   #   Time.now   #=> 2013-11-07 18:06:50 -0500
   #   sleep(10)
   #   task.value #=> 2013-11-07 18:06:55 -0500
@@ -87,11 +87,11 @@ module Concurrent
   #     task.execution_interval += 1
   #     if task.execution_interval > 5
   #       puts 'Stopping...'
-  #       task.stop
+  #       task.shutdown
   #     end
   #   end
   #   
-  #   timer_task.run # blocking call - this task will stop itself
+  #   timer_task.execute # blocking call - this task will stop itself
   #   #=> Boom!
   #   #=> Boom! Boom!
   #   #=> Boom! Boom! Boom!
@@ -114,30 +114,30 @@ module Concurrent
   #   
   #   task = Concurrent::TimerTask.new(execution_interval: 1, timeout_interval: 1){ 42 }
   #   task.add_observer(TaskObserver.new)
-  #   task.run!
+  #   task.execute
   #   
   #   #=> (2013-10-13 19:08:58 -0400) Execution successfully returned 42
   #   #=> (2013-10-13 19:08:59 -0400) Execution successfully returned 42
   #   #=> (2013-10-13 19:09:00 -0400) Execution successfully returned 42
-  #   task.stop
+  #   task.shutdown
   #   
   #   task = Concurrent::TimerTask.new(execution_interval: 1, timeout_interval: 1){ sleep }
   #   task.add_observer(TaskObserver.new)
-  #   task.run!
+  #   task.execute
   #   
   #   #=> (2013-10-13 19:07:25 -0400) Execution timed out
   #   #=> (2013-10-13 19:07:27 -0400) Execution timed out
   #   #=> (2013-10-13 19:07:29 -0400) Execution timed out
-  #   task.stop
+  #   task.shutdown
   #   
   #   task = Concurrent::TimerTask.new(execution_interval: 1){ raise StandardError }
   #   task.add_observer(TaskObserver.new)
-  #   task.run!
+  #   task.execute
   #   
   #   #=> (2013-10-13 19:09:37 -0400) Execution failed with error StandardError
   #   #=> (2013-10-13 19:09:38 -0400) Execution failed with error StandardError
   #   #=> (2013-10-13 19:09:39 -0400) Execution failed with error StandardError
-  #   task.stop
+  #   task.shutdown
   #
   # @see http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html
   # @see http://docs.oracle.com/javase/7/docs/api/java/util/TimerTask.html
@@ -316,7 +316,7 @@ module Concurrent
     # @!visibility private
     def execute_task(completion)
       return unless @running.true?
-      Concurrent::timer(timeout_interval, completion, &method(:timeout_task))
+      Concurrent::timer(execution_interval, completion, &method(:timeout_task))
       success, value, reason = @executor.execute(self)
       if completion.try?
         self.value = value