concurrent-ruby 0.7.0 → 0.7.1

data/lib/concurrent/actor/behaviour/supervised.rb

@@ -3,7 +3,8 @@ module Concurrent
     module Behaviour
 
       # Sets and holds the supervisor of the actor if any. There is at most one supervisor
-      # for each actor. Each supervisor is automatically linked.
+      # for each actor. Each supervisor is automatically linked. Messages:
+      # `:pause!, :resume!, :reset!, :restart!` are accepted only from supervisor.
       class Supervised < Abstract
         attr_reader :supervisor
 

data/lib/concurrent/actor/behaviour/termination.rb

@@ -44,7 +44,7 @@ module Concurrent
         def terminate!
           return true if terminated?
           terminated.set
-          broadcast(:terminated)
+          broadcast(:terminated) # TODO do not end up in Dead Letter Router
           parent << :remove_child if parent
           true
         end

data/lib/concurrent/actor/context.rb

@@ -115,7 +115,8 @@ module Concurrent
       undef_method :spawn
     end
 
-    # Basic Context of an Actor.
+    # Basic Context of an Actor. It does not support supervision and pausing.
+    # It simply terminates on error.
     #
     # -   linking
     # -   terminates on error

data/lib/concurrent/actor/core.rb

@@ -46,10 +46,14 @@ module Concurrent
         synchronize do
           @mailbox              = Array.new
           @serialized_execution = SerializedExecution.new
-          @executor             = Type! opts.fetch(:executor, Concurrent.configuration.global_task_pool), Executor
           @children             = Set.new
-          @context_class        = Child! opts.fetch(:class), AbstractContext
+
+          @context_class = Child! opts.fetch(:class), AbstractContext
           allocate_context
+
+          @executor = Type! opts.fetch(:executor, Concurrent.configuration.global_task_pool), Executor
+          raise ArgumentError, 'ImmediateExecutor is not supported' if @executor.is_a? ImmediateExecutor
+
           @reference = (Child! opts[:reference_class] || @context.default_reference_class, Reference).new self
           @name      = (Type! opts.fetch(:name), String, Symbol).to_s
 
@@ -82,7 +86,7 @@ module Concurrent
                 handle_envelope Envelope.new(message, nil, parent, reference)
               end
 
-              initialized.set true if initialized
+              initialized.set reference if initialized
             rescue => ex
               log ERROR, ex
               @first_behaviour.terminate!

data/lib/concurrent/actor/utils/balancer.rb

@@ -4,6 +4,7 @@ module Concurrent
 
       # Distributes messages between subscribed actors. Each actor'll get only one message then
       # it's unsubscribed. The actor needs to resubscribe when it's ready to receive next message.
+      # It will buffer the messages if there is no worker registered.
       # @see Pool
       class Balancer < RestartingContext
 
@@ -24,14 +25,15 @@ module Concurrent
           when :subscribed?
             @receivers.include? envelope.sender
           else
-            @buffer << message
+            @buffer << envelope
             distribute
+            Behaviour::MESSAGE_PROCESSED
           end
         end
 
         def distribute
           while !@receivers.empty? && !@buffer.empty?
-            @receivers.shift << @buffer.shift
+            redirect @receivers.shift, @buffer.shift
           end
         end
       end

data/lib/concurrent/actor/utils/pool.rb

@@ -34,7 +34,7 @@ module Concurrent
         end
 
         def on_message(message)
-          @balancer << message
+          redirect @balancer
         end
       end
 

data/lib/concurrent/agent.rb

@@ -8,28 +8,7 @@ require 'concurrent/logging'
 
 module Concurrent
 
-  # An agent is a single atomic value that represents an identity. The current value
-  # of the agent can be requested at any time (`#deref`). Each agent has a work queue and operates on
-  # the global thread pool. Consumers can `#post` code blocks to the agent. The code block (function)
-  # will receive the current value of the agent as its sole parameter. The return value of the block
-  # will become the new value of the agent. Agents support two error handling modes: fail and continue.
-  # A good example of an agent is a shared incrementing counter, such as the score in a video game.
-  #
-  # @example Basic usage
-  #   score = Concurrent::Agent.new(10)
-  #   score.value #=> 10
-  #   
-  #   score << proc{|current| current + 100 }
-  #   sleep(0.1)
-  #   score.value #=> 110
-  #   
-  #   score << proc{|current| current * 2 }
-  #   sleep(0.1)
-  #   score.value #=> 220
-  #   
-  #   score << proc{|current| current - 50 }
-  #   sleep(0.1)
-  #   score.value #=> 170
+  # {include:file:doc/agent.md}
   #
   # @!attribute [r] timeout
   #   @return [Fixnum] the maximum number of seconds before an update is cancelled

data/lib/concurrent/async.rb

@@ -8,85 +8,7 @@ require 'concurrent/executor/serialized_execution'
 
 module Concurrent
 
-  # A mixin module that provides simple asynchronous behavior to any standard
-  # class/object or object. 
-  #
-  #   Scenario:
-  #     As a stateful, plain old Ruby class/object
-  #     I want safe, asynchronous behavior
-  #     So my long-running methods don't block the main thread
-  #
-  # Stateful, mutable objects must be managed carefully when used asynchronously.
-  # But Ruby is an object-oriented language so designing with objects and classes
-  # plays to Ruby's strengths and is often more natural to many Ruby programmers.
-  # The `Async` module is a way to mix simple yet powerful asynchronous capabilities
-  # into any plain old Ruby object or class. These capabilities provide a reasonable
-  # level of thread safe guarantees when used correctly.
-  #
-  # When this module is mixed into a class or object it provides to new methods:
-  # `async` and `await`. These methods are thread safe with respect to the enclosing
-  # object. The former method allows methods to be called asynchronously by posting
-  # to the global thread pool. The latter allows a method to be called synchronously
-  # on the current thread but does so safely with respect to any pending asynchronous
-  # method calls. Both methods return an `Obligation` which can be inspected for
-  # the result of the method call. Calling a method with `async` will return a
-  # `:pending` `Obligation` whereas `await` will return a `:complete` `Obligation`.
-  #
-  # Very loosely based on the `async` and `await` keywords in C#.
-  #
-  # @example Defining an asynchronous class
-  #   class Echo
-  #     include Concurrent::Async
-  #
-  #     def initialize
-  #       init_mutex # initialize the internal synchronization objects
-  #     end
-  #
-  #     def echo(msg)
-  #       sleep(rand)
-  #       print "#{msg}\n"
-  #       nil
-  #     end
-  #   end
-  #   
-  #   horn = Echo.new
-  #   horn.echo('zero') # synchronous, not thread-safe
-  #
-  #   horn.async.echo('one') # asynchronous, non-blocking, thread-safe
-  #   horn.await.echo('two') # synchronous, blocking, thread-safe
-  #
-  # @example Monkey-patching an existing object
-  #   numbers = 1_000_000.times.collect{ rand }
-  #   numbers.extend(Concurrent::Async)
-  #   numbers.init_mutex # initialize the internal synchronization objects
-  #   
-  #   future = numbers.async.max
-  #   future.state #=> :pending
-  #   
-  #   sleep(2)
-  #   
-  #   future.state #=> :fulfilled
-  #   future.value #=> 0.999999138918843
-  #
-  # @note This module depends on several internal synchronization objects that
-  #       must be initialized prior to calling any of the async/await/executor methods.
-  #       The best practice is to call `init_mutex` from within the constructor
-  #       of the including class. A less ideal but acceptable practice is for the
-  #       thread creating the asynchronous object to explicitly call the `init_mutex`
-  #       method prior to calling any of the async/await/executor methods. If
-  #       `init_mutex` is *not* called explicitly the async/await/executor methods
-  #       will raize a `Concurrent::InitializationError`. This is the only way 
-  #       thread-safe initialization can be guaranteed.
-  #
-  # @note Thread safe guarantees can only be made when asynchronous method calls
-  #       are not mixed with synchronous method calls. Use only synchronous calls
-  #       when the object is used exclusively on a single thread. Use only
-  #       `async` and `await` when the object is shared between threads. Once you
-  #       call a method using `async`, you should no longer call any methods
-  #       directly on the object. Use `async` and `await` exclusively from then on.
-  #       With careful programming it is possible to switch back and forth but it's
-  #       also very easy to create race conditions and break your application.
-  #       Basically, it's "async all the way down."
+  # {include:file:doc/async.md}
   #
   # @since 0.6.0
   #

data/lib/concurrent/atomic.rb

@@ -25,7 +25,7 @@ begin
 
   require "concurrent/atomic_reference/#{ruby_engine}"
 rescue LoadError
-  warn 'Compiled extensions not installed, pure Ruby Atomic will be used.'
+  #warn 'Compiled extensions not installed, pure Ruby Atomic will be used.'
 end
 
 if defined? Concurrent::JavaAtomic

data/lib/concurrent/atomic/thread_local_var.rb

@@ -2,41 +2,83 @@ require 'concurrent/atomic'
 
 module Concurrent
 
-  module ThreadLocalRubyStorage
+  # @!macro [attach] abstract_thread_local_var
+  #   A `ThreadLocalVar` is a variable where the value is different for each thread.
+  #   Each variable may have a default value, but when you modify the variable only
+  #   the current thread will ever see that change.
+  #   
+  #   @example
+  #     v = ThreadLocalVar.new(14)
+  #     v.value #=> 14
+  #     v.value = 2
+  #     v.value #=> 2
+  #   
+  #   @example
+  #     v = ThreadLocalVar.new(14)
+  #   
+  #     t1 = Thread.new do
+  #       v.value #=> 14
+  #       v.value = 1
+  #       v.value #=> 1
+  #     end
+  #   
+  #     t2 = Thread.new do
+  #       v.value #=> 14
+  #       v.value = 2
+  #       v.value #=> 2
+  #     end
+  #   
+  #     v.value #=> 14
+  class AbstractThreadLocalVar
 
-    def allocate_storage
-      @storage = Atomic.new Hash.new
-    end
+    module ThreadLocalRubyStorage
 
-    def get
-      @storage.get[Thread.current]
-    end
+      protected
 
-    def set(value)
-      @storage.update { |s| s.merge Thread.current => value }
-    end
+      unless RUBY_PLATFORM == 'java'
+        require 'ref'
+      end
 
-  end
+      def allocate_storage
+        @storage = Ref::WeakKeyMap.new
+      end
 
-  module ThreadLocalJavaStorage
+      def get
+        @storage[Thread.current]
+      end
 
-    protected
+      def set(value, &block)
+        key = Thread.current
 
-    def allocate_storage
-      @var = java.lang.ThreadLocal.new
-    end
+        @storage[key] = value
 
-    def get
-      @var.get
+        if block_given?
+          begin
+            block.call
+          ensure
+            @storage.delete key
+          end
+        end
+      end
     end
 
-    def set(value)
-      @var.set(value)
-    end
+    module ThreadLocalJavaStorage
 
-  end
+      protected
 
-  class AbstractThreadLocalVar
+      def allocate_storage
+        @var = java.lang.ThreadLocal.new
+      end
+
+      def get
+        @var.get
+      end
+
+      def set(value)
+        @var.set(value)
+      end
+
+    end
 
     NIL_SENTINEL = Object.new
 
@@ -58,19 +100,24 @@ module Concurrent
     end
 
     def value=(value)
+      bind value
+    end
+
+    def bind(value, &block)
       if value.nil?
         stored_value = NIL_SENTINEL
       else
         stored_value = value
       end
 
-      set stored_value
+      set stored_value, &block
 
       value
     end
 
   end
 
+  # @!macro abstract_thread_local_var
   class ThreadLocalVar < AbstractThreadLocalVar
     if RUBY_PLATFORM == 'java'
       include ThreadLocalJavaStorage

data/lib/concurrent/atomics.rb

@@ -7,5 +7,4 @@ require 'concurrent/atomic/copy_on_write_observer_set'
 require 'concurrent/atomic/cyclic_barrier'
 require 'concurrent/atomic/count_down_latch'
 require 'concurrent/atomic/event'
-require 'concurrent/atomic/thread_local_var'
 require 'concurrent/atomic/synchronization'

data/lib/concurrent/configuration.rb

@@ -17,6 +17,9 @@ module Concurrent
     #   lambda { |level, progname, message = nil, &block| _ }
     attr_accessor :logger
 
+    # defines if executors should be auto-terminated in at_exit callback
+    attr_accessor :auto_terminate
+
     # Create a new configuration object.
     def initialize
       immediate_executor     = ImmediateExecutor.new
@@ -24,6 +27,7 @@ module Concurrent
       @global_operation_pool = Delay.new(executor: immediate_executor) { new_operation_pool }
       @global_timer_set      = Delay.new(executor: immediate_executor) { Concurrent::TimerSet.new }
       @logger                = no_logger
+      @auto_terminate        = true
     end
 
     # if assigned to {#logger}, it will log nothing.
@@ -129,6 +133,12 @@ module Concurrent
     yield(configuration)
   end
 
+  def self.finalize_global_executors
+    self.finalize_executor(self.configuration.global_timer_set)
+    self.finalize_executor(self.configuration.global_task_pool)
+    self.finalize_executor(self.configuration.global_operation_pool)
+  end
+
   private
 
   # Attempt to properly shutdown the given executor using the `shutdown` or
@@ -150,12 +160,8 @@ module Concurrent
     false
   end
 
-
   # set exit hook to shutdown global thread pools
   at_exit do
-    self.finalize_executor(self.configuration.global_timer_set)
-    self.finalize_executor(self.configuration.global_task_pool)
-    self.finalize_executor(self.configuration.global_operation_pool)
-    # TODO may break other test suites using concurrent-ruby, terminates before test is run
+    finalize_global_executors if configuration.auto_terminate
   end
 end

data/lib/concurrent/dataflow.rb

@@ -19,36 +19,7 @@ module Concurrent
     end
   end
 
-  # Dataflow allows you to create a task that will be scheduled then all of its
-  # data dependencies are available. Data dependencies are `Future` values. The
-  # dataflow task itself is also a `Future` value, so you can build up a graph of
-  # these tasks, each of which is run when all the data and other tasks it depends
-  # on are available or completed.
-  #
-  # Our syntax is somewhat related to that of Akka's `flow` and Habanero Java's
-  # `DataDrivenFuture`. However unlike Akka we don't schedule a task at all until
-  # it is ready to run, and unlike Habanero Java we pass the data values into the
-  # task instead of dereferencing them again in the task.
-  #
-  # The theory of dataflow goes back to the 80s. In the terminology of the literature,
-  # our implementation is coarse-grained, in that each task can be many instructions,
-  # and dynamic in that you can create more tasks within other tasks.
-  #
-  # @example Parallel Fibonacci calculator
-  #   def fib(n)
-  #     if n < 2
-  #       Concurrent::dataflow { n }
-  #     else
-  #       n1 = fib(n - 1)
-  #       n2 = fib(n - 2)
-  #       Concurrent::dataflow(n1, n2) { |v1, v2| v1 + v2 }
-  #     end
-  #   end
-  #   
-  #   f = fib(14) #=> #<Concurrent::Future:0x000001019a26d8 ...
-  #   
-  #   # wait up to 1 second for the answer...
-  #   f.value(1) #=> 377
+  # {include:file:doc/dataflow.md}
   #
   # @param [Future] inputs zero or more `Future` operations that this dataflow depends upon
   #

data/lib/concurrent/dereferenceable.rb

@@ -3,8 +3,15 @@ module Concurrent
   # Object references in Ruby are mutable. This can lead to serious problems when
   # the `#value` of a concurrent object is a mutable reference. Which is always the
   # case unless the value is a `Fixnum`, `Symbol`, or similar "primitive" data type.
-  # Most classes in this library that expose a `#value` getter method do so using
-  # this mixin module.
+  # Most classes in this library that expose a `#value` getter method do so using the
+  # `Dereferenceable` mixin module. 
+  # 
+  # Objects with this mixin can be configured with a few options that can help protect
+  # the program from potentially dangerous operations.
+  # 
+  # * `:dup_on_deref` when true  will call the `#dup` method on the `value` object every time the `#value` method is called (default: false)
+  # * `:freeze_on_deref` when true  will call the `#freeze` method on the `value` object every time the `#value` method is called (default: false)
+  # * `:copy_on_deref` when given a `Proc` object the `Proc` will be run every time the `#value` method is called. The `Proc` will be given the current `value` as its only parameter and the result returned by the block will be the return value of the `#value` call. When `nil` this option will be ignored (default: nil)
   module Dereferenceable
 
     # Return the value this object represents after applying the options specified