More documentation

Author: pitr-ch

lib/concurrent/actress.rb

@@ -5,14 +5,7 @@
 
 module Concurrent
 
-  # @example ping
-  #   class Ping
-  #     include Context
-  #     def on_message(message)
-  #       message
-  #     end
-  #   end
-  #   Ping.spawn(:ping1).ask(:m).value #=> :m
+  # {include:file:lib/concurrent/actress/doc.md}
   module Actress
 
     require 'concurrent/actress/type_check'
@@ -47,7 +40,7 @@ def on_message(message)
     ROOT = Core.new(parent: nil, name: '/', class: Root).reference
 
     # @param block for actress_class instantiation
-    # @param args see {#spawn_optionify}
+    # @param args see {.spawn_optionify}
     def self.spawn(*args, &block)
       if Actress.current
         Core.new(spawn_optionify(*args).merge(parent: Actress.current), &block).reference
@@ -56,7 +49,7 @@ def self.spawn(*args, &block)
       end
     end
 
-    # as {#spawn} but it'll raise when Actor not initialized properly
+    # 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
@@ -66,7 +59,7 @@ def self.spawn!(*args, &block)
     #   @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.new} opts
+    #   see {Core#initialize} opts
     def self.spawn_optionify(*args)
       if args.size == 1 && args.first.is_a?(Hash)
         args.first

lib/concurrent/actress/doc.md

@@ -0,0 +1,53 @@
+# Light-weighted implement of Actors. Inspired by Akka and Erlang.
+
+Actors are using a thread-pool by default which makes them very cheap to create and discard.
+Thousands of actors can be created allowing to brake the program to small maintainable pieces
+without breaking single responsibility principles.
+
+## Quick example
+    
+    class Counter
+      include Context
+    
+      def initialize(initial_value)
+        @count = initial_value
+      end
+    
+      def on_message(message)
+        case message
+        when Integer
+          @count += message
+        when :terminate
+          terminate!
+        else
+          raise 'unknown'
+        end
+      end
+    end
+    
+    # create new actor
+    counter = Counter.spawn(:test_counter, 5) # => a Reference
+    
+    # send messages
+    counter.tell(1) # => counter
+    counter << 1 # => counter
+    
+    # send messages getting an IVar back for synchronization
+    counter.ask(0) # => an ivar
+    counter.ask(0).value # => 7
+    
+    # terminate the actor
+    counter.ask(:terminate).wait
+    counter.terminated? # => true
+    counter.ask(5).wait.rejected? # => true
+    
+    # failure on message processing will terminate the actor
+    counter = Counter.spawn(:test_counter, 0)
+    counter.ask('boom').wait.rejected? # => true
+    counter.terminated? # => true
+
+
+    
+
+
+

lib/concurrent/actress/reference.rb

@@ -33,7 +33,7 @@ def ask(message, ivar = IVar.new)
         message message, ivar
       end
 
-      # @note can lead to deadlocks
+      # @note can lead to deadlocks, use only in tests or when you are sure it won't deadlock
       # tells message to the actor
       # @param [Object] message
       # @param [Ivar] ivar to be fulfilled be message's processing result

lib/concurrent/configuration.rb

@@ -11,6 +11,8 @@ module Concurrent
   # A gem-level configuration object.
   class Configuration
 
+    # a proc defining how to log messages, its interface has to be:
+    #   lambda { |level, progname, message = nil, &block| _ }
     attr_accessor :logger
 
     # Create a new configuration object.
@@ -21,6 +23,7 @@ def initialize
       @logger                = no_logger
     end
 
+    # if assigned to {#logger}, it will log nothing.
     def no_logger
       -> (level, progname, message = nil, &block) {}
     end

lib/concurrent/logging.rb

@@ -1,9 +1,15 @@
 require 'logger'
 
 module Concurrent
+  # Include where logging is needed
   module Logging
     include Logger::Severity
 
+    # Logs through {Configuration#logger}, it can be overridden by setting @logger
+    # @param [Integer] level one of Logger::Severity constants
+    # @param [String] progname e.g. a path of an Actor
+    # @param [String, nil] message when nil block is used to generate the message
+    # @yields_return [String] a message
     def log(level, progname, message = nil, &block)
       (@logger || Concurrent.configuration.logger).call level, progname, message, &block
     end