concurrent-ruby 0.7.0.rc1 → 0.7.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2ed2814eb1b1cb9be1e9d71fe9326695755d20d5
-  data.tar.gz: ee3675edde539d3407ced1444f2792458b8381c4
+  metadata.gz: 73a8e3bc96ca01692b250022cbcf97543317527c
+  data.tar.gz: 7ce79ae51af42fe8acc907bf8ac8cc05ee3c3a85
 SHA512:
-  metadata.gz: b3e509ebdab47485679861a39b2e97b2cfb0d82004921514b9d173fde1f222e5f377821799147f58293f65840a9412112b602911a4933e283e56267ab1dc8eb0
-  data.tar.gz: 24155204863ce4a00cdfc2ac8ac72045e44d0f8022f18c0fd769a30c0fdc8eee6cc5615b4b8dccfd470f76669e1522b6ec85554701241a9b7c1724eda4809e58
+  metadata.gz: 2ea5e1c22fab46efeba404f1286bcd1362f35c4dc343f88d7b85bb145e5e0a6b30a9afb3aaeb92e7ebc847108e867a6fe1d125308fc5fb6e4e31bcb05d2ecf54
+  data.tar.gz: d955009ca3fc8cfd5e0c4f795f0af1bca57db62280d42de051e766bd83348a4eabb744435eb62e5d77f14c4b1d91394f249ef029009353aa8cdcab632ac02056

data/README.md

@@ -1,5 +1,5 @@
 # Concurrent Ruby
-[![Gem Version](https://badge.fury.io/rb/concurrent-ruby.png)](http://badge.fury.io/rb/concurrent-ruby) [![Build Status](https://travis-ci.org/ruby-concurrency/concurrent-ruby.svg?branch=master)](https://travis-ci.org/ruby-concurrency/concurrent-ruby) [![Coverage Status](https://coveralls.io/repos/ruby-concurrency/concurrent-ruby/badge.png)](https://coveralls.io/r/ruby-concurrency/concurrent-ruby) [![Code Climate](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby.png)](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby) [![Inline docs](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby.png)](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby) [![Dependency Status](https://gemnasium.com/ruby-concurrency/concurrent-ruby.png)](https://gemnasium.com/ruby-concurrency/concurrent-ruby) [![Gitter chat](https://badges.gitter.im/ruby-concurrency.png)](https://gitter.im/ruby-concurrency)
+[![Gem Version](https://badge.fury.io/rb/concurrent-ruby.png)](http://badge.fury.io/rb/concurrent-ruby) [![Build Status](https://travis-ci.org/ruby-concurrency/concurrent-ruby.svg?branch=master)](https://travis-ci.org/ruby-concurrency/concurrent-ruby) [![Coverage Status](https://coveralls.io/repos/ruby-concurrency/concurrent-ruby/badge.png)](https://coveralls.io/r/ruby-concurrency/concurrent-ruby) [![Code Climate](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby.png)](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby) [![Inline docs](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby.png)](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby) [![Dependency Status](https://gemnasium.com/ruby-concurrency/concurrent-ruby.png)](https://gemnasium.com/ruby-concurrency/concurrent-ruby) [![Gitter chat](https://badges.gitter.im/ruby-concurrency/concurrent-ruby.png)](https://gitter.im/ruby-concurrency/concurrent-ruby)
 
 <table>
   <tr>
@@ -54,7 +54,7 @@ _NOTE: There is an old gem from 2007 called "concurrent" that does not appear to
 ## Features & Documentation
 
 Please see the [Concurrent Ruby Wiki](https://github.com/ruby-concurrency/concurrent-ruby/wiki)
-or the [API documentation](http://ruby-concurrency.github.io/concurrent-ruby/frames.html))
+or the [API documentation](http://ruby-concurrency.github.io/concurrent-ruby/frames.html)
 for more information or join our [mailing list](http://groups.google.com/group/concurrent-ruby).
 
 There are many concurrency abstractions in this library. These abstractions can be broadly categorized
@@ -146,6 +146,7 @@ task.value #=> 25.96
 * [Chip Miller](https://github.com/chip-miller)
 * [Giuseppe Capizzi](https://github.com/gcapizzi)
 * [Jamie Hodge](https://github.com/jamiehodge)
+* [Justin Lambert](https://github.com/mastfish)
 * [Larry Lv](https://github.com/larrylv)
 * [Maxim Chechel](https://github.com/maximchick)
 * [Ravil Bayramgalin](https://github.com/brainopia)

data/lib/concurrent.rb

@@ -8,8 +8,9 @@ require 'concurrent/collections'
 require 'concurrent/executors'
 require 'concurrent/utilities'
 
-require 'concurrent/actress'
+require 'concurrent/actor'
 require 'concurrent/atomic'
+require 'concurrent/lazy_register'
 require 'concurrent/agent'
 require 'concurrent/async'
 require 'concurrent/dataflow'

data/lib/concurrent/actor.rb

@@ -0,0 +1,104 @@
+require 'concurrent/configuration'
+require 'concurrent/executor/serialized_execution'
+require 'concurrent/ivar'
+require 'concurrent/logging'
+require 'concurrent/atomic/synchronization'
+
+module Concurrent
+  # TODO https://github.com/celluloid/celluloid/wiki/Supervision-Groups
+
+  # TODO doc
+  # - what happens if I try to supervise using a normal Context?
+
+
+  # {include:file:doc/actor/main.md}
+  module Actor
+
+    require 'concurrent/actor/type_check'
+    require 'concurrent/actor/errors'
+    require 'concurrent/actor/public_delegations'
+    require 'concurrent/actor/internal_delegations'
+    require 'concurrent/actor/envelope'
+    require 'concurrent/actor/reference'
+    require 'concurrent/actor/core'
+    require 'concurrent/actor/behaviour'
+    require 'concurrent/actor/context'
+
+    require 'concurrent/actor/default_dead_letter_handler'
+    require 'concurrent/actor/root'
+    require 'concurrent/actor/ad_hoc'
+
+    # @return [Reference, nil] current executing actor if any
+    def self.current
+      Thread.current[:__current_actor__]
+    end
+
+    @root = Delay.new do
+      Core.new(parent: nil, name: '/', class: Root, initialized: ivar = IVar.new).reference.tap do
+        ivar.no_error!
+      end
+    end
+
+    # A root actor, a default parent of all actors spawned outside an actor
+    def self.root
+      @root.value!
+    end
+
+    # Spawns a new actor.
+    #
+    # @example simple
+    #   Actor.spawn(AdHoc, :ping1) { -> message { message } }
+    #
+    # @example complex
+    #   Actor.spawn name:     :ping3,
+    #                 class:    AdHoc,
+    #                 args:     [1]
+    #                 executor: Concurrent.configuration.global_task_pool do |add|
+    #     lambda { |number| number + add }
+    #   end
+    #
+    # @param block for context_class instantiation
+    # @param args see {.spawn_optionify}
+    # @return [Reference] never the actual actor
+    def self.spawn(*args, &block)
+      experimental_acknowledged? or
+          warn '[EXPERIMENTAL] A full release of `Actor`, is expected in the 0.7.0 release.'
+
+      if Actor.current
+        Core.new(spawn_optionify(*args).merge(parent: Actor.current), &block).reference
+      else
+        root.ask([:spawn, spawn_optionify(*args), block]).value
+      end
+    end
+
+    # as {.spawn} but it'll raise when Actor not initialized properly
+    def self.spawn!(*args, &block)
+      spawn(spawn_optionify(*args).merge(initialized: ivar = IVar.new), &block).tap { ivar.no_error! }
+    end
+
+    # @overload spawn_optionify(context_class, name, *args)
+    #   @param [Context] context_class to be spawned
+    #   @param [String, Symbol] name of the instance, it's used to generate the {Core#path} of the actor
+    #   @param args for context_class instantiation
+    # @overload spawn_optionify(opts)
+    #   see {Core#initialize} opts
+    def self.spawn_optionify(*args)
+      if args.size == 1 && args.first.is_a?(Hash)
+        args.first
+      else
+        { class: args[0],
+          name:  args[1],
+          args:  args[2..-1] }
+      end
+    end
+
+    # call this to disable experimental warning
+    def self.i_know_it_is_experimental!
+      @experimental_acknowledged = true
+    end
+
+    def self.experimental_acknowledged?
+      !!@experimental_acknowledged
+    end
+  end
+end

data/lib/concurrent/{actress → actor}/ad_hoc.rb

@@ -1,13 +1,12 @@
 module Concurrent
-  module Actress
+  module Actor
     # 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
-      include Context
+    class AdHoc < Context
       def initialize(*args, &initializer)
         @on_message = Type! initializer.call(*args), Proc
       end

data/lib/concurrent/actor/behaviour.rb

@@ -0,0 +1,70 @@
+module Concurrent
+  module Actor
+
+    # Actors have modular architecture, which is achieved by combining a light core with chain of
+    # behaviours. Each message or internal event propagates through the chain allowing the
+    # behaviours react based on their responsibility. listing few as an example:
+    #
+    # -   {Behaviour::Linking}:
+    #
+    #     > {include:Actor::Behaviour::Linking}
+    #
+    # -   {Behaviour::Awaits}:
+    #
+    #     > {include:Actor::Behaviour::Awaits}
+    #
+    # See {Behaviour}'s namespace fo other behaviours.
+    # If needed new behaviours can be added, or old one removed to get required behaviour.
+    module Behaviour
+      MESSAGE_PROCESSED = Object.new
+
+      require 'concurrent/actor/behaviour/abstract'
+      require 'concurrent/actor/behaviour/awaits'
+      require 'concurrent/actor/behaviour/buffer'
+      require 'concurrent/actor/behaviour/errors_on_unknown_message'
+      require 'concurrent/actor/behaviour/executes_context'
+      require 'concurrent/actor/behaviour/linking'
+      require 'concurrent/actor/behaviour/pausing'
+      require 'concurrent/actor/behaviour/removes_child'
+      require 'concurrent/actor/behaviour/sets_results'
+      require 'concurrent/actor/behaviour/supervised'
+      require 'concurrent/actor/behaviour/supervising'
+      require 'concurrent/actor/behaviour/termination'
+      require 'concurrent/actor/behaviour/terminates_children'
+
+      def self.basic_behaviour_definition
+        [*base,
+         *user_messages(:terminate!)]
+      end
+
+      def self.restarting_behaviour_definition
+        [*base,
+         *supervised,
+         [Behaviour::Supervising, [:reset!, :one_for_one]],
+         *user_messages(:pause!)]
+      end
+
+      def self.base
+        [[SetResults, [:terminate!]],
+         # has to be before Termination to be able to remove children form terminated actor
+         [RemovesChild, []],
+         [Termination, []],
+         [TerminatesChildren, []],
+         [Linking, []]]
+      end
+
+      def self.supervised
+        [[Supervised, []],
+         [Pausing, []]]
+      end
+
+      def self.user_messages(on_error)
+        [[Buffer, []],
+         [SetResults, [on_error]],
+         [Awaits, []],
+         [ExecutesContext, []],
+         [ErrorsOnUnknownMessage, []]]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+module Concurrent
+  module Actor
+    module Behaviour
+      class Abstract
+        include TypeCheck
+        include InternalDelegations
+
+        attr_reader :core, :subsequent
+
+        def initialize(core, subsequent)
+          @core       = Type! core, Core
+          @subsequent = Type! subsequent, Abstract, NilClass
+        end
+
+        # override to add extra behaviour
+        # @note super needs to be called not to break the chain
+        def on_envelope(envelope)
+          pass envelope
+        end
+
+        # @param [Envelope] envelope to pass to {#subsequent} behaviour
+        def pass(envelope)
+          subsequent.on_envelope envelope
+        end
+
+        # override to add extra behaviour
+        # @note super needs to be called not to break the chain
+        def on_event(event)
+          subsequent.on_event event if subsequent
+        end
+
+        # broadcasts event to all behaviours and context
+        # @see #on_event
+        # @see AbstractContext#on_event
+        def broadcast(event)
+          core.broadcast(event)
+        end
+
+        def reject_envelope(envelope)
+          envelope.reject! ActorTerminated.new(reference)
+          dead_letter_routing << envelope unless envelope.ivar
+          log Logging::DEBUG, "rejected #{envelope.message} from #{envelope.sender_path}"
+        end
+      end
+    end
+  end
+end
+

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

@@ -0,0 +1,21 @@
+module Concurrent
+  module Actor
+    module Behaviour
+
+      # Handles `:await` messages. Which allows to wait on Actor to process all previously send
+      # messages.
+      # @example
+      #   actor << :a << :b
+      #   actor.ask(:await).wait # blocks until :a and :b are processed
+      class Awaits < Abstract
+        def on_envelope(envelope)
+          if envelope.message == :await
+            true
+          else
+            pass envelope
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+module Concurrent
+  module Actor
+    module Behaviour
+
+      # Any message reaching this behaviour is buffered. Only one message is is scheduled
+      # at any given time. Others are kept in buffer until another one can be scheduled.
+      # This effective means that messages handled by behaviours before buffer have higher priority
+      # and they can be processed before messages arriving into buffer. This allows to
+      # process internal actor messages like (`:link`, `:supervise`) processed first.
+      class Buffer < Abstract
+        def initialize(core, subsequent)
+          super core, subsequent
+          @buffer                     = []
+          @receive_envelope_scheduled = false
+        end
+
+        def on_envelope(envelope)
+          @buffer.push envelope
+          process_envelopes?
+          MESSAGE_PROCESSED
+        end
+
+        # Ensures that only one envelope processing is scheduled with #schedule_execution,
+        # this allows other scheduled blocks to be executed before next envelope processing.
+        # Simply put this ensures that Core is still responsive to internal calls (like add_child)
+        # even though the Actor is flooded with messages.
+        def process_envelopes?
+          unless @buffer.empty? || @receive_envelope_scheduled
+            @receive_envelope_scheduled = true
+            process_envelope
+          end
+        end
+
+        def process_envelope
+          envelope = @buffer.shift
+          return nil unless envelope
+          pass envelope
+        ensure
+          @receive_envelope_scheduled = false
+          core.schedule_execution { process_envelopes? }
+        end
+
+        def on_event(event)
+          case event
+          when :terminated, :restarted
+            @buffer.each { |envelope| reject_envelope envelope }
+            @buffer.clear
+          end
+          super event
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+module Concurrent
+  module Actor
+    module Behaviour
+      # Simply fails when message arrives here.
+      class ErrorsOnUnknownMessage < Abstract
+        def on_envelope(envelope)
+          raise UnknownMessage, envelope
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+module Concurrent
+  module Actor
+    module Behaviour
+      # Delegates messages nad events to {AbstractContext} instance
+      class ExecutesContext < Abstract
+        def on_envelope(envelope)
+          context.on_envelope envelope
+        end
+
+        def on_event(event)
+          context.on_event(event)
+          core.log Logging::DEBUG, "event: #{event.inspect}"
+          super event
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module Concurrent
+  module Actor
+    module Behaviour
+
+      # Links the actor to other actors and sends events to them,
+      # like: `:terminated`, `:paused`, errors, etc
+      class Linking < Abstract
+        def initialize(core, subsequent)
+          super core, subsequent
+          @linked = Set.new
+        end
+
+        def on_envelope(envelope)
+          case envelope.message
+          when :link
+            link envelope.sender
+          when :unlink
+            unlink envelope.sender
+          else
+            pass envelope
+          end
+        end
+
+        def link(ref)
+          @linked.add(ref)
+          true
+        end
+
+        def unlink(ref)
+          @linked.delete(ref)
+          true
+        end
+
+        def on_event(event)
+          @linked.each { |a| a << event }
+          @linked.clear if event == :terminated
+          super event
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+module Concurrent
+  module Actor
+    module Behaviour
+
+      # 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.
+      class Pausing < Abstract
+        def initialize(core, subsequent)
+          super core, subsequent
+          @paused = false
+          @buffer = []
+        end
+
+        def on_envelope(envelope)
+          case envelope.message
+          when :pause!
+            pause!
+          when :resume!
+            resume!
+          when :reset!
+            reset!
+          when :restart!
+            restart!
+          else
+            if @paused
+              @buffer << envelope
+              MESSAGE_PROCESSED
+            else
+              pass envelope
+            end
+          end
+        end
+
+        def pause!(error = nil)
+          @paused = true
+          broadcast(error || :paused)
+          true
+        end
+
+        def resume!(broadcast = true)
+          @paused = false
+          broadcast(:resumed) if broadcast
+          true
+        end
+
+        def reset!(broadcast = true)
+          core.allocate_context
+          core.build_context
+          resume!(false)
+          broadcast(:reset) if broadcast
+          true
+        end
+
+        def restart!
+          reset! false
+          broadcast(:restarted)
+          true
+        end
+
+        def on_event(event)
+          case event
+          when :terminated, :restarted
+            @buffer.each { |envelope| reject_envelope envelope }
+            @buffer.clear
+          when :resumed, :reset
+            @buffer.each { |envelope| core.schedule_execution { pass envelope } }
+            @buffer.clear
+          end
+          super event
+        end
+      end
+    end
+  end
+end