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

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

@@ -2,8 +2,9 @@ module Concurrent
   module Actor
     module Behaviour
 
-      # Links the actor to other actors and sends events to them,
+      # Links the actor to other actors and sends actor's events to them,
       # like: `:terminated`, `:paused`, errors, etc
+      # TODO example
       class Linking < Abstract
         def initialize(core, subsequent)
           super core, subsequent
@@ -16,6 +17,8 @@ module Concurrent
             link envelope.sender
           when :unlink
             unlink envelope.sender
+          when :linked?
+            @linked.include? envelope.sender
           else
             pass envelope
           end

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

@@ -5,8 +5,8 @@ module Concurrent
       # Allows to pause actors on errors.
       # When paused all arriving messages are collected and processed after the actor
       # is resumed or reset. Resume will simply continue with next message.
-      # Reset also reinitialized context. `:reset!` and `:resume!` messages are only accepted
-      # form supervisor, see Supervised behaviour.
+      # Reset also reinitialized context.
+      # TODO example
       class Pausing < Abstract
         def initialize(core, subsequent)
           super core, subsequent

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

@@ -2,8 +2,9 @@ module Concurrent
   module Actor
     module Behaviour
 
-      # Sets nad holds the supervisor of the actor if any. There is only one or none supervisor
-      # for each actor. Each supervisor is automatically linked.
+      # Sets and holds the supervisor of the actor if any. There is at most one supervisor
+      # 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/terminates_children.rb

@@ -4,7 +4,7 @@ module Concurrent
       # Terminates all children when the actor terminates.
       class TerminatesChildren < Abstract
         def on_event(event)
-          children.each { |ch| ch << :terminate! } if event == :terminated
+          children.map { |ch| ch.ask :terminate! }.each(&:wait) if event == :terminated
           super event
         end
       end

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

@@ -37,7 +37,7 @@ module Concurrent
       # @option opts [true, false] link, atomically link the actor to its parent
       # @option opts [true, false] supervise, atomically supervise the actor by its parent
       # @option opts [Array<Array(Behavior::Abstract, Array<Object>)>] behaviour_definition, array of pairs
-      #   where each pair is behaviour class and its args, see {Behaviour.basic_behaviour}
+      #   where each pair is behaviour class and its args, see {Behaviour.basic_behaviour_definition}
       # @option opts [IVar, nil] initialized, if present it'll be set or failed after {Context} initialization
       # @option opts [Proc, nil] logger a proc accepting (level, progname, message = nil, &block) params,
       #   can be used to hook actor instance to any logging system
@@ -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.rb

@@ -0,0 +1,10 @@
+module Concurrent
+  module Actor
+    module Utils
+      require 'concurrent/actor/utils/ad_hoc'
+      require 'concurrent/actor/utils/broadcast'
+      require 'concurrent/actor/utils/balancer'
+      require 'concurrent/actor/utils/pool'
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Concurrent
+  module Actor
+    module Utils
+      # Allows quick creation of actors with behaviour defined by blocks.
+      # @example ping
+      #   AdHoc.spawn :forward, an_actor do |where|
+      #     # this block has to return proc defining #on_message behaviour
+      #     -> message { where.tell message  }
+      #   end
+      class AdHoc < Context
+        def initialize(*args, &initializer)
+          @on_message = Type! initializer.call(*args), Proc
+        end
+
+        def on_message(message)
+          instance_exec message, &@on_message
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module Concurrent
+  module Actor
+    module Utils
+
+      # 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
+
+        def initialize
+          @receivers = []
+          @buffer    = []
+        end
+
+        def on_message(message)
+          case message
+          when :subscribe
+            @receivers << envelope.sender
+            distribute
+            true
+          when :unsubscribe
+            @receivers.delete envelope.sender
+            true
+          when :subscribed?
+            @receivers.include? envelope.sender
+          else
+            @buffer << envelope
+            distribute
+            Behaviour::MESSAGE_PROCESSED
+          end
+        end
+
+        def distribute
+          while !@receivers.empty? && !@buffer.empty?
+            redirect @receivers.shift, @buffer.shift
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -4,8 +4,20 @@ module Concurrent
   module Actor
     module Utils
 
-      # TODO doc
-      class Broadcast < Context
+      # Allows to build pub/sub easily.
+      # @example news
+      #   news_channel = Concurrent::Actor::Utils::Broadcast.spawn :news
+      #
+      #   2.times do |i|
+      #     Concurrent::Actor::Utils::AdHoc.spawn "listener-#{i}" do
+      #       news_channel << :subscribe
+      #       -> message { puts message }
+      #     end
+      #   end
+      #
+      #   news_channel << 'Ruby rocks!'
+      #   # prints: 'Ruby rocks!' twice
+      class Broadcast < RestartingContext
 
         def initialize
           @receivers = Set.new
@@ -14,11 +26,14 @@ module Concurrent
         def on_message(message)
           case message
           when :subscribe
-            @receivers.add envelope.sender
-            true
+            if envelope.sender.is_a? Reference
+              @receivers.add envelope.sender
+              true
+            else
+              false
+            end
           when :unsubscribe
-            @receivers.delete envelope.sender
-            true
+            !!@receivers.delete(envelope.sender)
           when :subscribed?
             @receivers.include? envelope.sender
           else
@@ -31,6 +46,7 @@ module Concurrent
           @receivers
         end
       end
+
     end
   end
 end

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

@@ -0,0 +1,59 @@
+require 'concurrent/actor/utils/balancer'
+
+module Concurrent
+  module Actor
+    module Utils
+
+      # Allows to create a pool of workers and distribute work between them
+      # @param [Integer] size number of workers
+      # @yield [balancer, index] a block spawning an worker instance. called +size+ times.
+      #   The worker should be descendant of AbstractWorker and supervised, see example.
+      # @yieldparam [Balancer] balancer to pass to the worker
+      # @yieldparam [Integer] index of the worker, usually used in its name
+      # @yieldreturn [Reference] the reference of newly created worker
+      # @example
+      #     class Worker < Concurrent::Actor::Utils::AbstractWorker
+      #       def work(message)
+      #         p message * 5
+      #       end
+      #     end
+      #
+      #     pool = Concurrent::Actor::Utils::Pool.spawn! 'pool', 5 do |balancer, index|
+      #       Worker.spawn name: "worker-#{index}", supervise: true, args: [balancer]
+      #     end
+      #
+      #     pool << 'asd' << 2
+      #     # prints:
+      #     # "asdasdasdasdasd"
+      #     # 10
+      class Pool < RestartingContext
+        def initialize(size, &worker_initializer)
+          @balancer = Balancer.spawn name: :balancer, supervise: true
+          @workers  = Array.new(size, &worker_initializer.curry[@balancer])
+          @workers.each { |w| Type! w, Reference }
+        end
+
+        def on_message(message)
+          redirect @balancer
+        end
+      end
+
+      class AbstractWorker < RestartingContext
+        def initialize(balancer)
+          @balancer = balancer
+          @balancer << :subscribe
+        end
+
+        def on_message(message)
+          work message
+        ensure
+          @balancer << :subscribe
+        end
+
+        def work(message)
+          raise NotImplementedError
+        end
+      end
+    end
+  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

@@ -1,3 +1,17 @@
+#####################################################################
+# Attempt to check for the deprecated ruby-atomic gem and warn the
+# user that they should use the new implementation instead.
+
+if defined?(Atomic)
+  warn <<-RUBY
+[ATOMIC] Detected an `Atomic` class, which may indicate a dependency
+on the ruby-atomic gem. That gem has been deprecated and merged into
+the concurrent-ruby gem. Please use the Concurrent::Atomic class for
+atomic references and not the Atomic class.
+RUBY
+end
+#####################################################################
+
 require 'concurrent/atomic_reference/concurrent_update_error'
 require 'concurrent/atomic_reference/mutex_atomic'
 
@@ -11,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
@@ -57,41 +71,21 @@ if defined? Concurrent::JavaAtomic
   class Concurrent::Atomic < Concurrent::JavaAtomic
   end
 
-elsif defined? Concurrent::CAtomic
-
-  # @!macro [attach] concurrent_update_error
-  #
-  # This exception may be thrown by methods that have detected concurrent
-  # modification of an object when such modification is not permissible.
-  class Concurrent::Atomic < Concurrent::CAtomic
-  end
-
 elsif defined? Concurrent::RbxAtomic
 
   # @!macro atomic_reference
   class Concurrent::Atomic < Concurrent::RbxAtomic
   end
 
-else
+elsif Concurrent.allow_c_native_class?('CAtomic')
 
   # @!macro atomic_reference
-  class Concurrent::Atomic < Concurrent::MutexAtomic
+  class Concurrent::Atomic < Concurrent::CAtomic
   end
-end
 
-# @!macro atomic_reference
-class Atomic < Concurrent::Atomic
-
-  # @!macro concurrent_update_error
-  ConcurrentUpdateError = Class.new(Concurrent::ConcurrentUpdateError)
+else
 
-  # @!macro [attach] atomic_reference_method_initialize
-  #
-  # Creates a new Atomic reference with null initial value.
-  #
-  # @param [Object] value the initial value
-  def initialize(value)
-    warn "[DEPRECATED] Please use Concurrent::Atomic instead."
-    super
+  # @!macro atomic_reference
+  class Concurrent::Atomic < Concurrent::MutexAtomic
   end
 end