Merge pull request #156 from ruby-concurrency/actress

Doc updates

Author: Petr Chalupa

doc/actor/quick.in.rb

@@ -29,32 +29,37 @@ def on_message(message)
 counter.ask(0).value
 
 # Terminate the actor.
-counter.tell(:terminate!)
+counter.tell :terminate!
 # Not terminated yet, it takes a while until the message is processed.
-counter.terminated?
+counter.ask! :terminated?
 # Waiting for the termination.
-counter.terminated.class
-counter.terminated.wait
-counter.terminated?
+event = counter.ask!(:terminated_event)
+event.class
+event.wait
+counter.ask! :terminated?
 # Any subsequent messages are rejected.
 counter.ask(5).wait.rejected?
 
 # Failure on message processing terminates the actor.
 counter = Counter.spawn(:first, 0)
 counter.ask('boom').wait.rejected?
-counter.terminated?
+counter.ask! :terminated?
 
 
 # Lets define an actor creating children actors.
 class Node < Concurrent::Actor::Context
+  def initialize
+    @last_child_id = 0
+  end
+
   def on_message(message)
     case message
     when :new_child
-      Node.spawn :child
+      Node.spawn "child-#{@last_child_id += 1}"
     when :how_many_children
       children.size
     else
-      raise 'unknown'
+      pass
     end
   end
 end #
@@ -70,5 +75,5 @@ def on_message(message)
 
 # Termination of an parent will also terminate all children.
 parent.ask('boom').wait #
-parent.terminated?
-child.terminated?
+counter.ask! :terminated?
+counter.ask! :terminated?

doc/actor/quick.out.rb

@@ -29,40 +29,46 @@ def on_message(message)
 counter.ask(0).value                               # => 7
 
 # Terminate the actor.
-counter.tell(:terminate!)                          # => #<Concurrent::Actor::Reference /first (Counter)>
+counter.tell :terminate!                           # => #<Concurrent::Actor::Reference /first (Counter)>
 # Not terminated yet, it takes a while until the message is processed.
-counter.terminated?                                # => false
+counter.ask! :terminated?                          # => true
 # Waiting for the termination.
-counter.terminated.class                           # => Concurrent::Event
-counter.terminated.wait                            # => true
-counter.terminated?                                # => true
+event = counter.ask!(:terminated_event)
+    # => #<Concurrent::Event:0x007f6208da3d30 @set=true, @mutex=#<Mutex:0x007f6208da3ce0>, @condition=#<Concurrent::Condition:0x007f6208da3cb8 @condition=#<Thread::ConditionVariable:0x007f6208da3c90>>>
+event.class                                        # => Concurrent::Event
+event.wait                                         # => true
+counter.ask! :terminated?                          # => true
 # Any subsequent messages are rejected.
 counter.ask(5).wait.rejected?                      # => true
 
 # Failure on message processing terminates the actor.
 counter = Counter.spawn(:first, 0)                 # => #<Concurrent::Actor::Reference /first (Counter)>
 counter.ask('boom').wait.rejected?                 # => false
-counter.terminated?                                # => false
+counter.ask! :terminated?                          # => false
 
 
 # Lets define an actor creating children actors.
 class Node < Concurrent::Actor::Context
+  def initialize
+    @last_child_id = 0
+  end
+
   def on_message(message)
     case message
     when :new_child
-      Node.spawn :child
+      Node.spawn "child-#{@last_child_id += 1}"
     when :how_many_children
       children.size
     else
-      raise 'unknown'
+      pass
     end
   end
 end 
 
 # Actors are tracking parent-child relationships
 parent = Node.spawn :parent                        # => #<Concurrent::Actor::Reference /parent (Node)>
 child  = parent.tell(:new_child).ask!(:new_child)
-    # => #<Concurrent::Actor::Reference /parent/child (Node)>
+    # => #<Concurrent::Actor::Reference /parent/child-2 (Node)>
 child.parent                                       # => #<Concurrent::Actor::Reference /parent (Node)>
 parent.ask!(:how_many_children)                    # => 2
 
@@ -72,5 +78,5 @@ def on_message(message)
 
 # Termination of an parent will also terminate all children.
 parent.ask('boom').wait 
-parent.terminated?                                 # => true
-child.terminated?                                  # => true
+counter.ask! :terminated?                          # => false
+counter.ask! :terminated?                          # => false

lib/concurrent/actor.rb

@@ -5,11 +5,17 @@
 require 'concurrent/atomic/synchronization'
 
 module Concurrent
-  # TODO https://github.com/celluloid/celluloid/wiki/Supervision-Groups
+  # TODO https://github.com/celluloid/celluloid/wiki/Supervision-Groups ?
+  # TODO Remote actors using DRb
+  # TODO IO interoperation
+  # TODO un/become
 
   # TODO doc
   # - what happens if I try to supervise using a normal Context?
-
+  # - how to change behaviours
+  # - how to implement custom restarting?
+  # - pool for io operations using different executor
+  # - document guaranteed ordering
 
   # {include:file:doc/actor/main.md}
   module Actor
@@ -77,7 +83,7 @@ def self.spawn!(*args, &block)
     end
 
     # @overload spawn_optionify(context_class, name, *args)
-    #   @param [Context] context_class to be spawned
+    #   @param [AbstractContext] 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)

lib/concurrent/actor/behaviour/errors_on_unknown_message.rb

@@ -1,7 +1,7 @@
 module Concurrent
   module Actor
     module Behaviour
-      # Simply fails when message arrives here.
+      # Simply fails when message arrives here. It's usually the last behaviour.
       class ErrorsOnUnknownMessage < Abstract
         def on_envelope(envelope)
           raise UnknownMessage, envelope

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 @@ def on_envelope(envelope)
             link envelope.sender
           when :unlink
             unlink envelope.sender
+          when :linked?
+            @linked.include? envelope.sender
           else
             pass envelope
           end

lib/concurrent/actor/behaviour/pausing.rb

@@ -5,8 +5,8 @@ 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.
+      # Reset also reinitialized context.
+      # TODO example
       class Pausing < Abstract
         def initialize(core, subsequent)
           super core, subsequent

lib/concurrent/actor/behaviour/supervised.rb

@@ -3,7 +3,8 @@ module Actor
     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
 

lib/concurrent/actor/behaviour/termination.rb

@@ -44,7 +44,7 @@ def on_envelope(envelope)
         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

lib/concurrent/actor/context.rb

@@ -115,7 +115,8 @@ def self.spawn_optionify(name_or_opts, *args)
       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

lib/concurrent/actor/utils/balancer.rb

@@ -4,6 +4,7 @@ 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