concurrent-ruby 0.6.0.pre.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 873e9e671b06398c80e8c918e5e2ba7c0d75564e
-  data.tar.gz: 69963957bf5e06a7a5b7ca21a678039496874c35
+  metadata.gz: 58bf31b4139ff60bd206c0771a4616653c77d710
+  data.tar.gz: 1fbbe6556817458272475deac127e92fc0c723a2
 SHA512:
-  metadata.gz: 92bb87ece26412064c4d9697b1d92ce1cc4963d74b6f9c32b32db091d216ff8655bbd1961322db8618666a571f4f9559cf7823aa9db1fa33687b2c45db1bb57a
-  data.tar.gz: 0d2645e119b50b88748b6131bcc984e127399bb9f5988fdfaa095fe915149ad03e60ab530523736006d3eb71a1b86821b6a889c032e9bd3c5d6a04a821d8ca2d
+  metadata.gz: 4d701a724fe2bb49c0bfa6c8cd3ccb242af88983ac04d90ac622a40a00e3e8e39b21a635a090c6dd808124f82733c66b99fabf05504691dcbe5a4a1f97ab8f33
+  data.tar.gz: 6bc189a09d26d754131c4ca8f09ec45912f2c0a4bb22ef3a578daa5781103df38597c8ab86573a78f211aa88f1f635188673b3d0d51334f56588b5c3d7c3f841

data/README.md

@@ -18,6 +18,8 @@ and classic concurrency patterns.
 <p>
 The design goals of this gem are:
 <ul>
+<li>Be an 'unopinionted' toolbox that provides useful utilities without debating which is better or why</li>
+<li>Remain free of external gem dependencies</li>
 <li>Stay true to the spirit of the languages providing inspiration</li>
 <li>But implement in a way that makes sense for Ruby</li>
 <li>Keep the semantics as idiomatic Ruby as possible</li>
@@ -126,14 +128,6 @@ task = Concurrent::ScheduledTask.execute(2){ Ticker.new.get_year_end_closing('IN
 task.state #=> :pending
 sleep(3)   # do other stuff
 task.value #=> 25.96
-
-# Async
-ticker = Ticker.new
-ticker.extend(Concurrent::Async)
-hpq = ticker.async.get_year_end_closing('HPQ', 2013)
-ibm = ticker.await.get_year_end_closing('IBM', 2013)
-hpq.value #=> 27.98
-ibm.value #=> 187.57
 ```
 
 ## Contributors
@@ -144,6 +138,7 @@ ibm.value #=> 187.57
 * [Lucas Allan](https://github.com/lucasallan)
 * [Petr Chalupa](https://github.com/pitr-ch)
 * [Ravil Bayramgalin](https://github.com/brainopia)
+* [Larry Lv](https://github.com/larrylv)
 * [Giuseppe Capizzi](https://github.com/gcapizzi)
 * [Brian Shirai](https://github.com/brixen)
 * [Chip Miller](https://github.com/chip-miller)

data/lib/concurrent.rb

@@ -13,6 +13,7 @@ require 'concurrent/async'
 require 'concurrent/dataflow'
 require 'concurrent/delay'
 require 'concurrent/dereferenceable'
+require 'concurrent/errors'
 require 'concurrent/exchanger'
 require 'concurrent/future'
 require 'concurrent/ivar'
@@ -27,6 +28,7 @@ require 'concurrent/stoppable'
 require 'concurrent/supervisor'
 require 'concurrent/timer_task'
 require 'concurrent/tvar'
+require 'concurrent/actress'
 
 # Modern concurrency tools for Ruby. Inspired by Erlang, Clojure, Scala, Haskell,
 # F#, C#, Java, and classic concurrency patterns.

data/lib/concurrent/actor/actor.rb

@@ -179,7 +179,7 @@ module Concurrent
     #
     # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     def self.pool(count, *args, &block)
-      warn '[DEPRECATED] `Actor` is deprecated and will be replaced with `ActorContext`.'
+      warn '[DEPRECATED] `Actor` is deprecated and will be replaced with `Actress`.'
       raise ArgumentError.new('count must be greater than zero') unless count > 0
       mailbox = Queue.new
       actors = count.times.collect do
@@ -212,7 +212,7 @@ module Concurrent
     # 
     # @!visibility public
     def act(*message)
-      warn '[DEPRECATED] `Actor` is deprecated and will be replaced with `ActorContext`.'
+      warn '[DEPRECATED] `Actor` is deprecated and will be replaced with `Actress`.'
       raise NotImplementedError.new("#{self.class} does not implement #act")
     end
 
@@ -220,7 +220,7 @@ module Concurrent
     #
     # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     def on_run # :nodoc:
-      warn '[DEPRECATED] `Actor` is deprecated and will be replaced with `ActorContext`.'
+      warn '[DEPRECATED] `Actor` is deprecated and will be replaced with `Actress`.'
       queue.clear
     end
 

data/lib/concurrent/actor/postable.rb

@@ -57,7 +57,7 @@ module Concurrent
 
     def post!(seconds, *message)
       raise ArgumentError.new('empty message') if message.empty?
-      raise Concurrent::Runnable::LifecycleError unless ready?
+      raise Concurrent::LifecycleError unless ready?
       raise Concurrent::TimeoutError if seconds.to_f <= 0.0
       event = Event.new
       cback = Queue.new

data/lib/concurrent/actors.rb

@@ -1,5 +1,2 @@
 require 'concurrent/actor/actor'
-require 'concurrent/actor/actor_context'
-require 'concurrent/actor/actor_ref'
 require 'concurrent/actor/postable'
-require 'concurrent/actor/simple_actor_ref'

data/lib/concurrent/actress.rb

@@ -0,0 +1,75 @@
+require 'concurrent/configuration'
+require 'concurrent/executor/one_by_one'
+require 'concurrent/ivar'
+require 'concurrent/logging'
+
+module Concurrent
+
+  # {include:file:lib/concurrent/actress/doc.md}
+  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_actress__]
+    end
+
+    # implements ROOT
+    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
+
+    # A root actor, a default parent of all actors spawned outside an actor
+    ROOT = Core.new(parent: nil, name: '/', class: Root).reference
+
+    # @param block for actress_class instantiation
+    # @param args see {.spawn_optionify}
+    def self.spawn(*args, &block)
+      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)
+      warn '[EXPERIMENTAL] A full release of `Actress`, renamed `Actor`, is expected in the 0.7.0 release.'
+      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 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
+  end
+end

data/lib/concurrent/actress/ad_hoc.rb

@@ -0,0 +1,14 @@
+module Concurrent
+  module Actress
+    class AdHoc
+      include 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

data/lib/concurrent/actress/context.rb

@@ -0,0 +1,96 @@
+module Concurrent
+  module Actress
+
+    # module used to define actor behaviours
+    # @example ping
+    #  class Ping
+    #    include Context
+    #    def on_message(message)
+    #      message
+    #    end
+    #  end
+    #
+    #  Ping.spawn(:ping1).ask(:m).value #=> :m
+    module Context
+      include TypeCheck
+      include CoreDelegations
+
+      attr_reader :core
+
+      # @abstract override to define Actor's behaviour
+      # @param [Object] message
+      # @return [Object] a result which will be used to set the IVar supplied to Reference#ask
+      # @note self should not be returned (or sent to other actors), {#reference} should be used
+      #   instead
+      def on_message(message)
+        raise NotImplementedError
+      end
+
+      def logger
+        core.logger
+      end
+
+      # @api private
+      def on_envelope(envelope)
+        @envelope = envelope
+        on_message envelope.message
+      ensure
+        @envelope = nil
+      end
+
+      # @see Actress.spawn
+      def spawn(*args, &block)
+        Actress.spawn(*args, &block)
+      end
+
+      # @see Core#children
+      def children
+        core.children
+      end
+
+      # @see Core#terminate!
+      def terminate!
+        core.terminate!
+      end
+
+      private
+
+      # @api private
+      def initialize_core(core)
+        @core = Type! core, Core
+      end
+
+      # @return [Envelope] current envelope, accessible inside #on_message processing
+      def envelope
+        @envelope or raise 'envelope not set'
+      end
+
+      def self.included(base)
+        base.extend ClassMethods
+        super base
+      end
+
+      module ClassMethods
+        # behaves as {Actress.spawn} but class_name is omitted
+        def spawn(name_or_opts, *args, &block)
+          Actress.spawn spawn_optionify(name_or_opts, *args), &block
+        end
+
+        # behaves as {Actress.spawn!} but class_name is omitted
+        def spawn!(name_or_opts, *args, &block)
+          Actress.spawn! spawn_optionify(name_or_opts, *args), &block
+        end
+
+        private
+
+        def spawn_optionify(name_or_opts, *args)
+          if name_or_opts.is_a? Hash
+            name_or_opts.merge class: self
+          else
+            { class: self, name: name_or_opts, args: args }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actress/core.rb

@@ -0,0 +1,204 @@
+module Concurrent
+  module Actress
+
+    require 'set'
+
+    # Core of the actor
+    # @api private
+    # @note devel: core should not block on anything, e.g. it cannot wait on children to terminate
+    #   that would eat up all threads in task pool and deadlock
+    class Core
+      include TypeCheck
+      include Concurrent::Logging
+
+      attr_reader :reference, :name, :path, :executor, :terminated
+
+      # @option opts [String] name
+      # @option opts [Reference, nil] parent of an actor spawning this one
+      # @option opts [Context] actress_class a class to be instantiated defining Actor's behaviour
+      # @option opts [Array<Object>] args arguments for actress_class instantiation
+      # @option opts [Executor] executor, default is `Concurrent.configuration.global_task_pool`
+      # @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
+      # @param [Proc] block for class instantiation
+      def initialize(opts = {}, &block)
+        @mailbox    = Array.new
+        @one_by_one = OneByOne.new
+        # noinspection RubyArgCount
+        @terminated = Event.new
+        @executor   = Type! opts.fetch(:executor, Concurrent.configuration.global_task_pool), Executor
+        @children   = Set.new
+        @reference  = Reference.new self
+        @name       = (Type! opts.fetch(:name), String, Symbol).to_s
+
+        parent       = opts[:parent]
+        @parent_core = (Type! parent, Reference, NilClass) && parent.send(:core)
+        if @parent_core.nil? && @name != '/'
+          raise 'only root has no parent'
+        end
+
+        @path   = @parent_core ? File.join(@parent_core.path, @name) : @name
+        @logger = opts[:logger]
+
+        @parent_core.add_child reference if @parent_core
+
+        @actress_class = actress_class = Child! opts.fetch(:class), Context
+        args           = opts.fetch(:args, [])
+        initialized    = Type! opts[:initialized], IVar, NilClass
+
+        schedule_execution do
+          begin
+            @actress = actress_class.new *args, &block
+            @actress.send :initialize_core, self
+            initialized.set true if initialized
+          rescue => ex
+            log ERROR, ex
+            terminate!
+            initialized.fail ex if initialized
+          end
+        end
+      end
+
+      # @return [Reference, nil] of parent actor
+      def parent
+        @parent_core && @parent_core.reference
+      end
+
+      # @return [Array<Reference>] of children actors
+      def children
+        guard!
+        @children.to_a
+      end
+
+      # @api private
+      def add_child(child)
+        guard!
+        Type! child, Reference
+        @children.add child
+        nil
+      end
+
+      # @api private
+      def remove_child(child)
+        schedule_execution do
+          Type! child, Reference
+          @children.delete child
+        end
+        nil
+      end
+
+      # is executed by Reference scheduling processing of new messages
+      # can be called from other alternative Reference implementations
+      # @param [Envelope] envelope
+      def on_envelope(envelope)
+        schedule_execution do
+          if terminated?
+            reject_envelope envelope
+          else
+            @mailbox.push envelope
+          end
+          process_envelopes?
+        end
+        nil
+      end
+
+      # @note Actor rejects envelopes when terminated.
+      # @return [true, false] if actor is terminated
+      def terminated?
+        @terminated.set?
+      end
+
+      # Terminates the actor. Any Envelope received after termination is rejected.
+      # Terminates all its children, does not wait until they are terminated.
+      def terminate!
+        guard!
+        @children.each do |ch|
+          ch.send(:core).tap { |core| core.send(:schedule_execution) { core.terminate! } }
+        end
+
+        @terminated.set
+
+        @parent_core.remove_child reference if @parent_core
+        @mailbox.each do |envelope|
+          reject_envelope envelope
+          log DEBUG, "rejected #{envelope.message} from #{envelope.sender_path}"
+        end
+        @mailbox.clear
+
+        nil
+      end
+
+      # @api private
+      # ensures that we are inside of the executor
+      def guard!
+        unless Actress.current == reference
+          raise "can be called only inside actor #{reference} but was #{Actress.current}"
+        end
+      end
+
+      private
+
+      # 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 @mailbox.empty? || @receive_envelope_scheduled
+          @receive_envelope_scheduled = true
+          schedule_execution { receive_envelope }
+        end
+      end
+
+      # Processes single envelope, calls #process_envelopes? at the end to ensure next envelope
+      # scheduling.
+      def receive_envelope
+        envelope = @mailbox.shift
+
+        if terminated?
+          reject_envelope envelope
+          log FATAL, "this should not be happening #{caller[0]}"
+        end
+
+        log DEBUG, "received #{envelope.message} from #{envelope.sender_path}"
+
+        result = @actress.on_envelope envelope
+        envelope.ivar.set result unless envelope.ivar.nil?
+
+        nil
+      rescue => error
+        log ERROR, error
+        terminate!
+        envelope.ivar.fail error unless envelope.ivar.nil?
+      ensure
+        @receive_envelope_scheduled = false
+        process_envelopes?
+      end
+
+      # Schedules blocks to be executed on executor sequentially,
+      # sets Actress.current
+      def schedule_execution
+        @one_by_one.post(@executor) do
+          begin
+            Thread.current[:__current_actress__] = reference
+            yield
+          rescue => e
+            log FATAL, e
+          ensure
+            Thread.current[:__current_actress__] = nil
+          end
+        end
+
+        nil
+      end
+
+      def reject_envelope(envelope)
+        envelope.reject! ActressTerminated.new(reference)
+      end
+
+      def log(level, message = nil, &block)
+        super level, @path, message, &block
+      end
+    end
+  end
+end