concurrent-ruby 0.7.0.rc1 → 0.7.0.rc2

data/lib/concurrent/actor/default_dead_letter_handler.rb

@@ -0,0 +1,9 @@
+module Concurrent
+  module Actor
+    class DefaultDeadLetterHandler < RestartingContext
+      def on_message(dead_letter)
+        log Logging::INFO, "got dead letter #{dead_letter.inspect}"
+      end
+    end
+  end
+end

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

@@ -1,5 +1,5 @@
 module Concurrent
-  module Actress
+  module Actor
     class Envelope
       include TypeCheck
 

data/lib/concurrent/actor/errors.rb

@@ -0,0 +1,27 @@
+module Concurrent
+  module Actor
+    Error = Class.new(StandardError)
+
+    class ActorTerminated < Error
+      include TypeCheck
+
+      attr_reader :reference
+
+      def initialize(reference)
+        @reference = Type! reference, Reference
+        super reference.path
+      end
+    end
+
+    class UnknownMessage < Error
+      include TypeCheck
+
+      attr_reader :envelope
+
+      def initialize(envelope)
+        @envelope = Type! envelope, Envelope
+        super envelope.message.inspect
+      end
+    end
+  end
+end

data/lib/concurrent/actor/internal_delegations.rb

@@ -0,0 +1,49 @@
+module Concurrent
+  module Actor
+    module InternalDelegations
+      include PublicDelegations
+
+      # @see Core#children
+      def children
+        core.children
+      end
+
+      # @see Core#terminate!
+      def terminate!
+        behaviour!(Behaviour::Termination).terminate!
+      end
+
+      # delegates to core.log
+      # @see Logging#log
+      def log(level, message = nil, &block)
+        core.log(level, message, &block)
+      end
+
+      # @see AbstractContext#dead_letter_routing
+      def dead_letter_routing
+        context.dead_letter_routing
+      end
+
+      def redirect(reference, envelope = self.envelope)
+        reference.message(envelope.message, envelope.ivar)
+        Behaviour::MESSAGE_PROCESSED
+      end
+
+      # @return [AbstractContext]
+      def context
+        core.context
+      end
+
+      # see Core#behaviour
+      def behaviour(behaviour_class)
+        core.behaviour(behaviour_class)
+      end
+
+      # see Core#behaviour!
+      def behaviour!(behaviour_class)
+        core.behaviour!(behaviour_class)
+      end
+
+    end
+  end
+end

data/lib/concurrent/{actress/core_delegations.rb → actor/public_delegations.rb}

@@ -1,42 +1,40 @@
 module Concurrent
-  module Actress
+  module Actor
 
     # Provides publicly expose-able methods from {Core}.
-    module CoreDelegations
+    module PublicDelegations
+      # @see Core#name
       def name
         core.name
       end
 
+      # @see Core#path
       def path
         core.path
       end
 
+      # @see Core#parent
       def parent
         core.parent
       end
 
-      def terminated?
-        core.terminated?
-      end
-
-      def terminated
-        core.terminated
-      end
-
+      # @see Core#reference
       def reference
         core.reference
       end
 
+      # @see Core#executor
       def executor
         core.executor
       end
 
-      def actor_class
-        core.actor_class
+      # @see Core#context_class
+      def context_class
+        core.context_class
       end
 
       alias_method :ref, :reference
-      alias_method :actress_class, :actor_class
+      alias_method :actor_class, :context_class
     end
   end
 end

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

@@ -1,12 +1,12 @@
 module Concurrent
-  module Actress
+  module Actor
 
     # Reference is public interface of Actor instances. It is used for sending messages and can
     # be freely passed around the program. It also provides some basic information about the actor,
-    # see {CoreDelegations}.
+    # see {PublicDelegations}.
     class Reference
       include TypeCheck
-      include CoreDelegations
+      include PublicDelegations
 
       attr_reader :core
       private :core
@@ -16,7 +16,7 @@ module Concurrent
         @core = Type! core, Core
       end
 
-      # tells message to the actor
+      # tells message to the actor, returns immediately
       # @param [Object] message
       # @return [Reference] self
       def tell(message)
@@ -25,7 +25,12 @@ module Concurrent
 
       alias_method :<<, :tell
 
-      # tells message to the actor
+      # @note it's a good practice to use tell whenever possible. Ask should be used only for
+      # testing and when it returns very shortly. It can lead to deadlock if all threads in
+      # global_task_pool will block on while asking. It's fine to use it form outside of actors and
+      # global_task_pool.
+      #
+      # sends message to the actor and asks for the result of its processing, returns immediately
       # @param [Object] message
       # @param [Ivar] ivar to be fulfilled be message's processing result
       # @return [IVar] supplied ivar
@@ -33,8 +38,12 @@ module Concurrent
         message message, ivar
       end
 
-      # @note can lead to deadlocks, use only in tests or when you are sure it won't deadlock
-      # tells message to the actor
+      # @note it's a good practice to use tell whenever possible. Ask should be used only for
+      # testing and when it returns very shortly. It can lead to deadlock if all threads in
+      # global_task_pool will block on while asking. It's fine to use it form outside of actors and
+      # global_task_pool.
+      #
+      # sends message to the actor and asks for the result of its processing, blocks
       # @param [Object] message
       # @param [Ivar] ivar to be fulfilled be message's processing result
       # @return [Object] message's processing result
@@ -45,10 +54,15 @@ module Concurrent
 
       # behaves as {#tell} when no ivar and as {#ask} when ivar
       def message(message, ivar = nil)
-        core.on_envelope Envelope.new(message, ivar, Actress.current || Thread.current, self)
+        core.on_envelope Envelope.new(message, ivar, Actor.current || Thread.current, self)
         return ivar || self
       end
 
+      # @see AbstractContext#dead_letter_routing
+      def dead_letter_routing
+        core.dead_letter_routing
+      end
+
       def to_s
         "#<#{self.class} #{path} (#{actor_class})>"
       end
@@ -58,6 +72,9 @@ module Concurrent
       def ==(other)
         Type? other, self.class and other.send(:core) == core
       end
+
+      # to avoid confusion with Kernel.spawn
+      undef_method :spawn
     end
 
   end

data/lib/concurrent/actor/root.rb

@@ -0,0 +1,37 @@
+module Concurrent
+  module Actor
+    # implements the root actor
+    class Root < AbstractContext
+
+      def initialize
+        # noinspection RubyArgCount
+        @dead_letter_router = Core.new(parent:    reference,
+                                       class:     DefaultDeadLetterHandler,
+                                       supervise: true,
+                                       name:      :default_dead_letter_handler).reference
+      end
+
+      # to allow spawning of new actors, spawn needs to be called inside the parent Actor
+      def on_message(message)
+        case
+        when message.is_a?(Array) && message.first == :spawn
+          Actor.spawn message[1], &message[2]
+        when message == :dead_letter_routing
+          @dead_letter_router
+        else
+          # ignore
+        end
+      end
+
+      def dead_letter_routing
+        @dead_letter_router
+      end
+
+      def behaviour_definition
+        [*Behaviour.base,
+         [Behaviour::Supervising, [:reset!, :one_for_one]],
+         *Behaviour.user_messages(:just_log)]
+      end
+    end
+  end
+end

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

@@ -1,5 +1,5 @@
 module Concurrent
-  module Actress
+  module Actor
 
     # taken from Algebrick
     # supplies type-checking helpers whenever included

data/lib/concurrent/actor/utills.rb

@@ -0,0 +1,7 @@
+module Concurrent
+  module Actor
+    module Utils
+      require 'concurrent/actor/utils/broadcast'
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+require 'set'
+
+module Concurrent
+  module Actor
+    module Utils
+
+      # TODO doc
+      class Broadcast < Context
+
+        def initialize
+          @receivers = Set.new
+        end
+
+        def on_message(message)
+          case message
+          when :subscribe
+            @receivers.add envelope.sender
+            true
+          when :unsubscribe
+            @receivers.delete envelope.sender
+            true
+          when :subscribed?
+            @receivers.include? envelope.sender
+          else
+            filtered_receivers.each { |r| r << message }
+          end
+        end
+
+        # override to define different behaviour, filtering etc
+        def filtered_receivers
+          @receivers
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actress.rb

@@ -1,225 +1,3 @@
-require 'concurrent/configuration'
-require 'concurrent/executor/serialized_execution'
-require 'concurrent/ivar'
-require 'concurrent/logging'
+require 'concurrent/actor'
 
-module Concurrent
-
-  # # Actor model
-  #
-  # -  Light-weighted.
-  # -  Inspired by Akka and Erlang.
-  #
-  # Actors are sharing a thread-pool by default which makes them very cheap to create and discard.
-  # Thousands of actors can be created, allowing you to break the program into small maintainable pieces,
-  # without violating the single responsibility principle.
-  #
-  # ## What is an actor model?
-  #
-  # [Wiki](http://en.wikipedia.org/wiki/Actor_model) says:
-  # The actor model in computer science is a mathematical model of concurrent computation
-  # that treats _actors_ as the universal primitives of concurrent digital computation:
-  # in response to a message that it receives, an actor can make local decisions,
-  # create more actors, send more messages, and determine how to respond to the next
-  # message received.
-  #
-  # ## Why?
-  #
-  # Concurrency is hard this is one of many ways how to simplify the problem.
-  # It is simpler to reason about actors than about locks (and all their possible states).
-  #
-  # ## How to use it
-  #
-  # {include:file:doc/actress/quick.out.rb}
-  #
-  # ## Messaging
-  #
-  # Messages are processed in same order as they are sent by a sender. It may interleaved with
-  # messages form other senders though. There is also a contract in actor model that
-  # messages sent between actors should be immutable. Gems like
-  #
-  # - [Algebrick](https://github.com/pitr-ch/algebrick) - Typed struct on steroids based on
-  #   algebraic types and pattern matching
-  # - [Hamster](https://github.com/hamstergem/hamster) - Efficient, Immutable, Thread-Safe
-  #   Collection classes for Ruby
-  #
-  # are very useful.
-  #
-  # ## Architecture
-  #
-  # Actors are running on shared thread poll which allows user to create many actors cheaply.
-  # Downside is that these actors cannot be directly used to do IO or other blocking operations.
-  # Blocking operations could starve the `default_task_pool`. However there are two options:
-  #
-  # - Create an regular actor which will schedule blocking operations in `global_operation_pool`
-  #   (which is intended for blocking operations) sending results back to self in messages.
-  # - Create an actor using `global_operation_pool` instead of `global_task_pool`, e.g.
-  #   `AnIOActor.spawn name: :blocking, executor: Concurrent.configuration.global_operation_pool`.
-  #
-  # Each actor is composed from 3 objects:
-  #
-  # ### {Reference}
-  # {include:Actress::Reference}
-  #
-  # ### {Core}
-  # {include:Actress::Core}
-  #
-  # ### {Context}
-  # {include:Actress::Context}
-  #
-  # ## Speed
-  #
-  # Simple benchmark Actress vs Celluloid, the numbers are looking good
-  # but you know how it is with benchmarks. Source code is in
-  # `examples/actress/celluloid_benchmark.rb`. It sends numbers between x actors
-  # and adding 1 until certain limit is reached.
-  #
-  # Benchmark legend:
-  #
-  # - mes.  - number of messages send between the actors
-  # - act.  - number of actors exchanging the messages
-  # - impl. - which gem is used
-  #
-  # ### JRUBY
-  #
-  #     Rehearsal --------------------------------------------------------
-  #     50000    2 actress    24.110000   0.800000  24.910000 (  7.728000)
-  #     50000    2 celluloid  28.510000   4.780000  33.290000 ( 14.782000)
-  #     50000  500 actress    13.700000   0.280000  13.980000 (  4.307000)
-  #     50000  500 celluloid  14.520000  11.740000  26.260000 ( 12.258000)
-  #     50000 1000 actress    10.890000   0.220000  11.110000 (  3.760000)
-  #     50000 1000 celluloid  15.600000  21.690000  37.290000 ( 18.512000)
-  #     50000 1500 actress    10.580000   0.270000  10.850000 (  3.646000)
-  #     50000 1500 celluloid  14.490000  29.790000  44.280000 ( 26.043000)
-  #     --------------------------------------------- total: 201.970000sec
-  #     
-  #      mes. act.      impl.      user     system      total        real
-  #     50000    2 actress     9.820000   0.510000  10.330000 (  5.735000)
-  #     50000    2 celluloid  10.390000   4.030000  14.420000 (  7.494000)
-  #     50000  500 actress     9.880000   0.200000  10.080000 (  3.310000)
-  #     50000  500 celluloid  12.430000  11.310000  23.740000 ( 11.727000)
-  #     50000 1000 actress    10.590000   0.190000  10.780000 (  4.029000)
-  #     50000 1000 celluloid  14.950000  23.260000  38.210000 ( 20.841000)
-  #     50000 1500 actress    10.710000   0.250000  10.960000 (  3.892000)
-  #     50000 1500 celluloid  13.280000  30.030000  43.310000 ( 24.620000) (1)
-  #
-  # ### MRI 2.1.0
-  #
-  #     Rehearsal --------------------------------------------------------
-  #     50000    2 actress     4.640000   0.080000   4.720000 (  4.852390)
-  #     50000    2 celluloid   6.110000   2.300000   8.410000 (  7.898069)
-  #     50000  500 actress     6.260000   2.210000   8.470000 (  7.400573)
-  #     50000  500 celluloid  10.250000   4.930000  15.180000 ( 14.174329)
-  #     50000 1000 actress     6.300000   1.860000   8.160000 (  7.303162)
-  #     50000 1000 celluloid  12.300000   7.090000  19.390000 ( 17.962621)
-  #     50000 1500 actress     7.410000   2.610000  10.020000 (  8.887396)
-  #     50000 1500 celluloid  14.850000  10.690000  25.540000 ( 24.489796)
-  #     ---------------------------------------------- total: 99.890000sec
-  #     
-  #      mes. act.      impl.      user     system      total        real
-  #     50000    2 actress     4.190000   0.070000   4.260000 (  4.306386)
-  #     50000    2 celluloid   6.490000   2.210000   8.700000 (  8.280051)
-  #     50000  500 actress     7.060000   2.520000   9.580000 (  8.518707)
-  #     50000  500 celluloid  10.550000   4.980000  15.530000 ( 14.699962)
-  #     50000 1000 actress     6.440000   1.870000   8.310000 (  7.571059)
-  #     50000 1000 celluloid  12.340000   7.510000  19.850000 ( 18.793591)
-  #     50000 1500 actress     6.720000   2.160000   8.880000 (  7.929630)
-  #     50000 1500 celluloid  14.140000  10.130000  24.270000 ( 22.775288) (1)
-  #
-  # *Note (1):* Celluloid is using thread per actor so this bench is creating about 1500
-  # native threads. Actress is using constant number of threads.
-  module Actress
-
-    require 'concurrent/actress/type_check'
-    require 'concurrent/actress/errors'
-    require 'concurrent/actress/core_delegations'
-    require 'concurrent/actress/envelope'
-    require 'concurrent/actress/reference'
-    require 'concurrent/actress/core'
-    require 'concurrent/actress/context'
-
-    require 'concurrent/actress/ad_hoc'
-
-    # @return [Reference, nil] current executing actor if any
-    def self.current
-      Thread.current[:__current_actor__]
-    end
-
-    # implements the root actor
-    class Root
-      include Context
-      # to allow spawning of new actors, spawn needs to be called inside the parent Actor
-      def on_message(message)
-        if message.is_a?(Array) && message.first == :spawn
-          spawn message[1], &message[2]
-        else
-          # ignore
-        end
-      end
-    end
-
-    @root = Delay.new { Core.new(parent: nil, name: '/', class: Root).reference }
-
-    # 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
-    #   Actress.spawn(AdHoc, :ping1) { -> message { message } }
-    #
-    # @example complex
-    #   Actress.spawn name:     :ping3,
-    #                 class:    AdHoc,
-    #                 args:     [1]
-    #                 executor: Concurrent.configuration.global_task_pool do |add|
-    #     lambda { |number| number + add }
-    #   end
-    #
-    # @param block for actress_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 `Actress`, renamed `Actor`, is expected in the 0.7.0 release.'
-
-      if Actress.current
-        Core.new(spawn_optionify(*args).merge(parent: Actress.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(actress_class, name, *args)
-    #   @param [Context] actress_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 actress_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
+Concurrent::Actress = Concurrent::Actor