Doc update

Author: pitr-ch

doc/actor/main.md

@@ -2,6 +2,7 @@
 
 -  Light-weighted.
 -  Inspired by Akka and Erlang.
+-  Modular.
 
 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,
@@ -40,9 +41,9 @@ are very useful.
 
 ### Dead letter routing
 
-see {Context#dead_letter_routing} description:
+see {AbstractContext#dead_letter_routing} description:
 
-> {include:Actor::Context#dead_letter_routing}
+> {include:Actor::AbstractContext#dead_letter_routing}
 
 ## Architecture
 
@@ -55,20 +56,19 @@ Blocking operations could starve the `default_task_pool`. However there are two
 - 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:
+Each actor is composed from 4 parts:
 
 ### {Reference}
 {include:Actor::Reference}
 
 ### {Core}
 {include:Actor::Core}
 
-### {Context}
-{include:Actor::Context}
+### {AbstractContext}
+{include:Actor::AbstractContext}
 
-### Behaviours
-
-_TODO_ 
+### {Behaviour}
+{include:Actor::Behaviour}
 
 ## Speed
 

doc/actor/quick.in.rb

@@ -1,7 +1,6 @@
-class Counter
+class Counter < Concurrent::Actor::Context
   # Include context of an actor which gives this class access to reference and other information
   # about the actor, see PublicDelegations.
-  include Concurrent::Actor::Context
 
   # use initialize as you wish
   def initialize(initial_value)
@@ -47,22 +46,18 @@ def on_message(message)
 
 
 # Lets define an actor creating children actors.
-class Node
-  include Concurrent::Actor::Context
-
+class Node < Concurrent::Actor::Context
   def on_message(message)
     case message
     when :new_child
-      spawn self.class, :child
+      Node.spawn :child
     when :how_many_children
       children.size
-    when :terminate
-      terminate!
     else
       raise 'unknown'
     end
   end
-end
+end #
 
 # Actors are tracking parent-child relationships
 parent = Node.spawn :parent

doc/actor/quick.out.rb

@@ -1,7 +1,6 @@
-class Counter
+class Counter < Concurrent::Actor::Context
   # Include context of an actor which gives this class access to reference and other information
   # about the actor, see PublicDelegations.
-  include Concurrent::Actor::Context
 
   # use initialize as you wish
   def initialize(initial_value)
@@ -42,27 +41,23 @@ def on_message(message)
 
 # Failure on message processing terminates the actor.
 counter = Counter.spawn(:first, 0)                 # => #<Concurrent::Actor::Reference /first (Counter)>
-counter.ask('boom').wait.rejected?                 # => true
-counter.terminated?                                # => true
+counter.ask('boom').wait.rejected?                 # => false
+counter.terminated?                                # => false
 
 
 # Lets define an actor creating children actors.
-class Node
-  include Concurrent::Actor::Context
-
+class Node < Concurrent::Actor::Context
   def on_message(message)
     case message
     when :new_child
-      spawn self.class, :child
+      Node.spawn :child
     when :how_many_children
       children.size
-    when :terminate
-      terminate!
     else
       raise 'unknown'
     end
   end
-end                                                # => :on_message
+end 
 
 # Actors are tracking parent-child relationships
 parent = Node.spawn :parent                        # => #<Concurrent::Actor::Reference /parent (Node)>

lib/concurrent/actor/behaviour.rb

@@ -1,7 +1,20 @@
 module Concurrent
   module Actor
 
-    # TODO document dependencies
+    # 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
 

lib/concurrent/actor/behaviour/abstract.rb

@@ -12,18 +12,26 @@ def initialize(core, subsequent)
           @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

lib/concurrent/actor/behaviour/awaits.rb

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

lib/concurrent/actor/behaviour/buffer.rb

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

lib/concurrent/actor/behaviour/errors_on_unknown_message.rb

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

lib/concurrent/actor/behaviour/executes_context.rb

@@ -1,6 +1,7 @@
 module Concurrent
   module Actor
     module Behaviour
+      # Delegates messages nad events to {AbstractContext} instance
       class ExecutesContext < Abstract
         def on_envelope(envelope)
           context.on_envelope envelope

lib/concurrent/actor/behaviour/linking.rb

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

lib/concurrent/actor/behaviour/pausing.rb

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

lib/concurrent/actor/behaviour/removes_child.rb

@@ -1,6 +1,7 @@
 module Concurrent
   module Actor
     module Behaviour
+      # Removes terminated children.
       class RemovesChild < Abstract
         def on_envelope(envelope)
           if envelope.message == :remove_child

lib/concurrent/actor/behaviour/sets_results.rb

@@ -1,6 +1,7 @@
 module Concurrent
   module Actor
     module Behaviour
+      # Collects returning value and sets the IVar in the {Envelope} or error on failure.
       class SetResults < Abstract
         attr_reader :error_strategy
 

lib/concurrent/actor/behaviour/supervising.rb

@@ -1,6 +1,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.
       class Supervising < Abstract
         attr_reader :supervisor
 

lib/concurrent/actor/behaviour/terminates_children.rb

@@ -1,6 +1,7 @@
 module Concurrent
   module Actor
     module Behaviour
+      # Terminates all children when the actor terminates.
       class TerminatesChildren < Abstract
         def on_event(event)
           children.each { |ch| ch << :terminate! } if event == :terminated

lib/concurrent/actor/behaviour/termination.rb

@@ -1,6 +1,9 @@
 module Concurrent
   module Actor
     module Behaviour
+
+      # Handles actor termination.
+      # @note Actor rejects envelopes when terminated.
       class Termination < Abstract
 
         # @!attribute [r] terminated