opee 0.0.5 → 0.1.0

data/README.md

@@ -1,5 +1,5 @@
 # Opee gem
-An experimental Object-base Parallel Evaluation Environment
+An experimental Object-based Parallel Evaluation Environment
 
 The purpose of this gem is to explore setting up an environment that will run
 completely in parallel with minimum use of mutex synchronization. Actors only
@@ -14,17 +14,35 @@ This is no where close to being ready for prime time.
 
 Any comments, thoughts, or suggestions are welcome.
 
+## <a name="links">Links of Interest</a>
+
+[Not Your Usual Threading](http://www.ohler.com/dev/http://www.ohler.com/dev/not_your_usual_threading/not_your_usual_threading.html) discussion about how OPEE use changes the way multi-threaded systems are designed.
+
 ## <a name="release">Release Notes</a>
 
-### Release 0.0.5
+### Release 0.1.0
+
+ - Documented classes.
 
- - Added tests for WorkQueue.
+ - Added a rescuer attribute to the Env for global error handling.
 
- - Added busy method to Actor.
+ - Added Collector and Job classes along with unit tests.
 
 # Plans and Notes
 
+- add name or label to Actors so they can be discovered by name or symbol
+
 - pick a problem to test against
+ - drop file path into dir_wq
+ - pick up and decompose
+  - if dir then drop into queue again
+  - if file then send to filter actor
+   - may need to read start to determine text if no extention
+    - check for #! something and assume text/script
+    - if not one of know extension then search low chars that are not \n\r\t or other well knows in text
+    - cache text if file is read in
+  - if text send to through work queue density checker then to summary
+
  - file density distribution
   - find all files under a directory
   - detemine if the file is a text or bin file and only keep text files
@@ -34,8 +52,6 @@ Any comments, thoughts, or suggestions are welcome.
   - wait_finish
   - ask to print or write report
 
-- describe patterns for use
-
 ### License:
 
     Copyright (c) 2012, Peter Ohler

data/lib/opee.rb

@@ -7,3 +7,5 @@ require 'opee/env'
 require 'opee/actor'
 require 'opee/log'
 require 'opee/workqueue'
+require 'opee/job'
+require 'opee/collector'

data/lib/opee/actor.rb

@@ -1,12 +1,29 @@
 
 module Opee
-
+  # The Actor class is the base class for all the asynchronous Objects in
+  # OPEE. It accepts requests through the ask() method and excutes those
+  # methods on a thread dedicated to the Actor.
   class Actor
+    # value of @state that indicates the Actor is not currently processing requests
     STOPPED = 0
+    # value of @state that indicates the Actor is currently ready to process requests
     RUNNING = 1
+    # value of @state that indicates the Actor is shutting down
     CLOSING = 2
+    # value of @state that indicates the Actor is processing one request and
+    # will stop after that processing is complete
     STEP    = 3
 
+    # The current processing state of the Actor
+    attr_reader :state
+
+    # Initializes the Actor with the options specified. A new thread is
+    # created during intialization after calling the set_options() method.
+    # @param [Hash] options options to be used for initialization
+    # @option options [Fixnum] :max_queue_count maximum number of requests
+    #         that can be queued before backpressure is applied to the caller.
+    # @option options [Float] :ask_timeout timeout in seconds to wait
+    #         before raising a BusyError if the request queue if too long.
     def initialize(options={})
       @queue = []
       @idle = []
@@ -55,18 +72,29 @@ module Opee
               sleep(1.0)
             end
           rescue Exception => e
-            Env.log_rescue(e)
+            Env.rescue(e)
           end
         end
       end
     end
 
+    # Processes the initialize() options. Subclasses should call super.
+    # @param [Hash] options options to be used for initialization
+    # @option options [Fixnum] :max_queue_count maximum number of requests
+    #         that can be queued before backpressure is applied to the caller.
+    # @option options [Float] :ask_timeout timeout in seconds to wait
+    #         before raising a BusyError if the request queue is too long.
     def set_options(options)
       @max_queue_count = options.fetch(:max_queue_count, @max_queue_count)
-      @ask_timeout = options.fetch(:ask_timeout, @ask_timeout)
+      @ask_timeout = options.fetch(:ask_timeout, @ask_timeout).to_f
     end
 
-    # deep copy and freeze args if not already frozen or primitive types
+    # Calls {#ask}() but uses the specified timeout instead of the default
+    # {#ask_timeout} to determine how long to wait if the Actor's queue is full.
+    # @param [Fixnum|Float] timeout maximum time to wait trying to add a request to the Actor's queue
+    # @param [Symbol] op method to queue for the Actor
+    # @param [Array] *args arguments to the op method
+    # @raise [BusyError] if the request queue does not become available in the timeout specified
     def timeout_ask(timeout, op, *args)
       unless @max_queue_count.nil? || 0 == @max_queue_count || @queue.size() < @max_queue_count
         @ask_thread = Thread.current
@@ -80,10 +108,18 @@ module Opee
       @loop.wakeup() if RUNNING == @state
     end
 
+    # Queues an operation and arguments to be called when the Actor is ready.
+    # @param [Symbol] op method to queue for the Actor
+    # @param [Array] *args arguments to the op method
+    # @raise [BusyError] if the request queue does not become available in the {#ask_timeout} seconds
     def ask(op, *args)
       timeout_ask(@ask_timeout, op, *args)
     end
 
+    # Queues an operation and arguments to be called when the Actor is has no
+    # other requests to process.
+    # @param [Symbol] op method to queue for the Actor
+    # @param [Array] *args arguments to the op method
     def on_idle(op, *args)
       @idle_mutex.synchronize {
         @idle.insert(0, Act.new(op, args))
@@ -91,6 +127,10 @@ module Opee
       @loop.wakeup() if RUNNING == @state
     end
 
+    # Queues an operation and arguments to be called as soon as possible by
+    # the Actor. These requests take precedence over other ordinary requests.
+    # @param [Symbol] op method to queue for the Actor
+    # @param [Array] *args arguments to the op method
     def priority_ask(op, *args)
       @priority_mutex.synchronize {
         @priority.insert(0, Act.new(op, args))
@@ -98,47 +138,74 @@ module Opee
       @loop.wakeup() if RUNNING == @state
     end
 
+    # When an attempt is made to call a private method of the Actor it is
+    # places on the processing queue. Other methods cause a NoMethodError to
+    # be raised as it normally would.
+    # @param [Symbol] m method to queue for the Actor
+    # @param [Array] *args arguments to the op method
+    # @param [Proc] blk ignored
     def method_missing(m, *args, &blk)
       raise NoMethodError.new("undefine method '#{m}' for #{self.class}", m, args) unless respond_to?(m, true)
       ask(m, *args)
     end
 
+    # Returns the number of requests on all three request queues, the normal,
+    # priority, and idle queues.
+    # @return [Fixnum] number of queued requests
     def queue_count()
       @queue.length + @priority.length + @idle.length
     end
 
-    def busy?
+    # Returns the true if any requests are queued or a request is being processed.
+    # @return [true|false] true if busy, false otherwise
+    def busy?()
       @busy || !@queue.empty? || !@priority.empty? || !@idle.empty?
     end
 
+    # Returns the default timeout for the time to wait for the Actor to be
+    # ready to accept a request using the {#ask}() method.
+    # @return [Float] current timeout for the {#ask}() method
     def ask_timeout()
       @ask_timeout
     end
 
-    def max_queue_count
+    # Returns the maximum number of requests allowed on the normal processing
+    # queue. A value of nil indicates there is no limit.
+    # @return [NilClass|Fixnum] maximum number of request that can be queued
+    def max_queue_count()
       @max_queue_count
     end
 
+    # Causes the Actor to stop processing any more requests after the current
+    # request has finished.
     def stop()
       @state = STOPPED
     end
 
+    # Causes the Actor to process one request and then stop. The max_wait is
+    # used to avoid getting stuck if the processing takes too long.
+    # @param [Float|Fixnum] max_wait maximum time to wait for the step to complete
     def step(max_wait=5)
       @state = STEP
       @step_thread = Thread.current
       @loop.wakeup()
       sleep(max_wait)
+      @step_thread = nil
     end
 
+    # Wakes up the Actor if it has been stopped or if Env.shutdown() has been called.
     def wakeup()
       @loop.wakeup()
     end
 
+    # Restarts the Actor's processing thread.
     def start()
       @state = RUNNING
       @loop.wakeup()
     end
 
+    # Closes the Actor by exiting the processing thread and removing the Actor
+    # from the Env.
     def close()
       @state = CLOSING
       begin
@@ -153,14 +220,24 @@ module Opee
 
     private
 
+    # Sets the {#ask_timeout} value which limits how long a caller will wait
+    # before getting a BusyError when calling {#ask}(). This method is
+    # executed asynchronously.
+    # @param [Float] timeout seconds to set the ask_timeout to
     def ask_timeout=(timeout)
       @ask_timeout = timeout
     end
 
+    # Sets the {#max_queue_count} value which limits the number of requests
+    # that can be on the Actor's queue. This method is executed
+    # asynchronously.
+    # @param [Fixnum] max maximum number of requests or nil for no limit
     def max_queue_count=(max)
       @max_queue_count = max
     end
 
+    # Internal class used to store information about asynchronous method
+    # invocations.
     class Act
       attr_accessor :op
       attr_accessor :args

data/lib/opee/collector.rb

@@ -0,0 +1,103 @@
+
+module Opee
+  # This class is used to collect multiple paths together before proceeding in
+  # a system. Two approaches are supported, either let the Collector subclass
+  # identify when it is time to move on or put the logic in the Job that is
+  # passed between the various Actors.
+  #
+  # To use a Collector, pass the same data along each path of Actors. All
+  # paths should terminate at the Collector. From there the Collector keeps a
+  # cache of the data's key and a token that is used to track arrivals. When
+  # all paths have converged the next Actor in the process is called.
+  class Collector < Actor
+    
+    def initialize(options={})
+      @cache = {}
+      @next_actor = nil
+      @next_method = nil
+      super(options)
+    end
+    
+    # Returns the number of Jobs currently waiting to be matched.
+    # @return [Fixnum] current number of Jobs waiting to finish.
+    def cache_size()
+      @cache.size()
+    end
+
+    private
+
+    # Processes the initialize() options. Subclasses should call super.
+    # @param [Hash] options options to be used for initialization
+    # @option options [Actor] :next_actor Actor to ask to continue when ready
+    # @option options [Symbol] :next_method method to ask of the next_actor to continue when ready
+    def set_options(options)
+      super(options)
+      @next_actor = options[:next_actor]
+      @next_method = options[:next_method]
+      @next_method = @next_method.to_sym if @next_method.is_a?(String)
+    end
+
+    # Collects a job and deternines if the job should be moved on to the next
+    # Actor or if it should wait until more processing paths have
+    # finished. This method is executed asynchronously.
+    # @param [Job|Object] job data to process or pass on
+    def collect(job, path_id=nil)
+      key = job_key(job)
+      token = @cache[key]
+      token = update_token(job, token, path_id)
+      if complete?(job, token)
+        @cache.delete(key)
+        keep_going(job)
+      else
+        @cache[key] = token
+      end
+    end
+
+    # Returns the key associated with the job. If the job responds to :key
+    # then that method is called, otherwise the subclass should implement this
+    # method. This method is executed asynchronously.
+    # @param [Object] job data to get the key for
+    # @return [Object] a key for looking up the token in the cache
+    def job_key(job)
+      raise NotImplementedError.new("neither Collector.job_key() nor Job.key() are implemented") unless job.respond_to?(:key)
+      job.key()
+    end
+
+    # Updates the token associated with the job. The job or the Collector
+    # subclass can use any data desired to keep track of the job's paths that
+    # have been completed. This method is executed asynchronously.
+    # @param [Object] job data to get the key for
+    # @param [Object] token current token value or nil for the first token value
+    # @param [Object] path_id an indicator of the path if used
+    # @return [Object] a token to keep track of the progress of the job
+    def update_token(job, token, path_id)
+      raise NotImplementedError.new("neither Collector.update_token() nor Job.update_token() are implemented") unless job.respond_to?(:update_token)
+      job.update_token(token, path_id)
+    end
+
+    # Returns true if the job has been processed by all paths converging on
+    # the collector. This can be implemented in the Collector subclass or in
+    # the Job. This method is executed asynchronously.
+    # @param [Object] job data to get the key for
+    # @param [Object] token current token value or nil for the first token value
+    # @return [true|false] an indication of wether the job has completed all paths
+    def complete?(job, token)
+      raise NotImplementedError.new("neither Collector.complete?() nor Job.complete?() are implemented") unless job.respond_to?(:complete?)
+      job.complete?(token)
+    end
+
+    # Moves the job onto the next Actor. If the job responds to :keep_going
+    # that is used, otherwise the @next_actor and @next_method care used to
+    # continue. This method is executed asynchronously.
+    # @param [Object] job data to get the key for
+    def keep_going(job)
+      if job.respond_to?(:keep_going)
+        job.keep_going()
+      else
+        # TBD @next_actor = Env.find_actor(@next_actor) if @next_actor.is_a?(Symbol)
+        @next_actor.send(@next_method, job)
+      end
+    end
+
+  end # Collector
+end # Opee

data/lib/opee/env.rb

@@ -1,27 +1,54 @@
 
+# Opee is an experimental Object-based Parallel Evaluation Environment
+#
+# The purpose of OPEE is to explore setting up an environment that will run
+# completely in parallel with minimum use of mutex synchronization. Actors
+# only push the flow forward, never returning values when using the ask()
+# method. Other methods return immediately but they should never modify the
+# data portions of the Actors. They can be used to modify the control
+# parameters of the Actor.
 module Opee
+  # The Env class hold all the global data for Opee. The global data could
+  # have been put directly under the Opee module but it seemed cleaner to keep
+  # it all together in an separate class.
   class Env
-
+    # Array of active Actors. This is private and should not be modified
+    # directly.
     @@actors = []
+    # global logger. This is private and should not be modified directly.
     @@log = nil
+    # used to wakup calling thread when ready. This is private and should not
+    # be modified directly.
     @@finish_thread = nil
+    # Actor that responds to rescue if set. This is private and should not be
+    # modified directly. Use the rescuer() or rescuer=() methods instead.
+    @@rescuer = nil
 
+    # Adds an Actor to the Env. This is called by the {Actor#initialize}() method.
+    # @param [Actor] actor actor to add
     def self.add_actor(actor)
       @@actors << actor
     end
 
+    # Removes an Actor from the Env. This is called by the {Actor#close}() method.
+    # @param [Actor] actor actor to remove
     def self.remove_actor(actor)
       @@actors.delete(actor)
     end
 
+    # Iterates over each active Actor and yields to the provided block with
+    # each Actor.
+    # @param [Proc] blk Proc to call on each iteration
     def self.each_actor(&blk)
       @@actors.each { |a| blk.yield(a) }
     end
 
+    # Returns the number of active Actors.
     def self.actor_count()
       @@actors.size
     end
 
+    # Closes all Actors and resets the logger to nil.
     def self.shutdown()
       until @@actors.empty?
         a = @@actors.pop()
@@ -30,31 +57,67 @@ module Opee
       @@log = nil
     end
 
+    # Asks the logger to log the message if the severity is high enough.
+    # @param [Fixnum] severity one of the Logger levels
+    # @param [String] message string to log
     def self.log(severity, message)
       @@log = Log.new() if @@log.nil?
       @@log.ask(:log, severity, message)
     end
 
+    # Asks the logger to log a message if the current severity level is less
+    # than or equal to Logger::DEBUG.
+    # @param [String] message string to log
     def self.debug(message)
       log(Logger::Severity::DEBUG, message)
     end
 
+    # Asks the logger to log a message if the current severity level is less
+    # than or equal to Logger::INFO.
+    # @param [String] message string to log
     def self.info(message)
       log(Logger::Severity::INFO, message)
     end
 
+    # Asks the logger to log a message if the current severity level is less
+    # than or equal to Logger::WARN.
+    # @param [String] message string to log
     def self.warn(message)
       log(Logger::Severity::WARN, message)
     end
 
+    # Asks the logger to log a message if the current severity level is less
+    # than or equal to Logger::ERROR.
+    # @param [String] message string to log
     def self.error(message)
       log(Logger::Severity::ERROR, message)
     end
 
+    # Asks the logger to log a message if the current severity level is less
+    # than or equal to Logger::FATAL.
+    # @param [String] message string to log
     def self.fatal(message)
       log(Logger::Severity::FATAL, message)
     end
 
+    # The log_rescue() method is called and then If a rescuer is set then it's
+    # rescue() method is called.
+    # @param [Exception] ex Exception to handle
+    def self.rescue(ex)
+      begin
+        log_rescue(ex)
+        @@rescuer.rescue(ex) unless @@rescuer.nil?
+      rescue Exception => e
+        puts "*** #{e.class}: #{e.message}"
+        e.backtrace.each { |line| puts "   " + line }
+      end
+    end
+
+    # Asks the logger to log a Exception class and message if the current
+    # severity level is less than or equal to Logger::ERROR. If the current
+    # severity is less than or equal to Logger::WARN then the Exception
+    # bactrace is also logged.
+    # @param [Exception] ex Exception to log
     def self.log_rescue(ex)
       @@log = Log.new() if @@log.nil?
       return unless Logger::Severity::ERROR >= @@log.level
@@ -65,37 +128,67 @@ module Opee
       @@log.ask(:log, Logger::Severity::ERROR, msg)
     end
 
+    # Returns the current Log Actor. If the current logger is nil then a new
+    # Log Actor is created and returned.
+    # @return [Log] the current logger
     def self.logger()
       @@log = Log.new() if @@log.nil?
       @@log
     end
 
+    # Sets the logger to the provided Log Actor. If the current logger is not
+    # nil then the current logger is closed first.
+    # @param [Log] log_actor Log Actor to use as the logger
+    # @raise [TypeError] raised if the log_actor is not a Log Actor
     def self.logger=(log_actor)
+      raise TypeError.new("can't convert #{log_actor.class} into a Opee::Log") unless log_actor.is_a?(Log)
       @@log.close() unless @@log.nil?
       @@log = log_actor
       @@log
     end
 
+    # Returns the current rescuer Actor. The rescuer us the Actor that is
+    # sent an Exception if an Exception is raised by an Actor.
+    # @return [Actor] the current rescuer
+    def self.rescuer()
+      @@rescuer
+    end
+
+    # Sets the rescuer to the provided Actor.
+    # @param [Actor] actor Actor to use as the rescuer and responds to :rescue
+    def self.rescuer=(actor)
+      @@rescuer = actor
+    end
+
+    # Returns the sum of all the requests in all the Actor's queues.
+    # @return [Fixnum] total number of items waiting to be processed
     def self.queue_count()
       cnt = 0
       @@actors.each { |a| cnt += a.queue_count() }
       cnt
     end
 
+    # Returns true of one or more Actors is either processing a request or has
+    # a request waiting to be processed on it's input queue.
+    # @return [true|false] the busy state across all Actors
     def self.busy?
       @@actors.each { |a| return true if a.busy? }
       false
     end
 
+    # Calls the stop() method on all Actors.
     def self.stop()
       @@actors.each { |a| a.stop() }
     end
 
+    # Calls the start() method on all Actors.
     def self.start()
       @@finish_thread = nil
       @@actors.each { |a| a.start() }
     end
 
+    # Waits for all Actors to complete processing. The method only returns
+    # when all Actors indicate they are no longer busy.
     def self.wait_finish()
       @@finish_thread = Thread.current
       @@actors.each { |a| a.wakeup() }
@@ -104,10 +197,13 @@ module Opee
       end
     end
 
+    # Wakes up the calling thread when an Actor is finished. It is called by
+    # the Actor and should not be called by any other code.
     def self.wake_finish()
       @@finish_thread.wakeup() unless @@finish_thread.nil?
     end
 
+    # Waits until all Actors are not longer busy and then closes all Actors.
     def self.wait_close()
       while 0 < queue_count()
         wait_finish()

data/lib/opee/errors.rb

@@ -1,11 +1,13 @@
 
 module Opee
+  # An Exception indicating an required option was missing.
   class MissingOptionError < Exception
     def initialize(option, msg)
       super("option #{option} for #{msg} missing")
     end
   end # MissingOptionError
 
+  # An Exception indicating an Actor was too busy to complete the requested operation.
   class BusyError < Exception
     def initialize()
       super("Busy, try again later")

data/lib/opee/job.rb

@@ -0,0 +1,43 @@
+
+module Opee
+  # A holder for data processed by Actors. It lends support to the use of
+  # Collectors if the support behavior is desired in the Job instead of the
+  # Collector itself.
+  class Job
+
+    def initialize()
+    end
+
+    # Returns the key associated with the job. The default behavior is to
+    # raise a NotImplementedError.
+    # @return [Object] a key for looking up the token in the cache
+    def key()
+      object_id()
+    end
+
+    # Updates the token associated with the job. The default behavior is to
+    # raise a NotImplementedError.
+    # @param [Object] token current token value or nil for the first token value
+    # @param [Object] path_id an indicator of the path if used
+    # @return [Object] a token to keep track of the progress of the job
+    def update_token(token, path_id)
+      raise NotImplementedError.new("update_token() not implemented")
+    end
+
+    # Returns true if the job has been processed by all paths converging on
+    # the collector. The default behavior is to raise a NotImplementedError.
+    # @param [Object] token current token value or nil for the first token value
+    # @return [true|false] an indication of wether the job has completed all paths
+    def complete?(token)
+      raise NotImplementedError.new("complete?() not implemented")
+    end
+
+    private
+
+    # Moves the job onto the next Actor.  Make public if implemented otherwise
+    # leave private so it is not called.
+    def keep_going()
+    end
+
+  end # Job
+end # Opee

data/lib/opee/log.rb

@@ -2,6 +2,8 @@
 require 'logger'
 
 module Opee
+  # An asynchronous logger build on top of the Actor class. It is able to log
+  # messages as well as forward calls to a {#forward} Actor.
   class Log < Actor
 
     def initialize(options={})
@@ -10,14 +12,20 @@ module Opee
       super(options)
     end
 
+    # Returns the current severity level.
+    # @return [Fixnum] Logger severity level
     def level()
       @logger.level
     end
 
+    # Returns the current formatter.
+    # @return [Logger::Formatter] current formatter
     def formatter()
       @logger.formatter
     end
 
+    # Returns the forward Log Actor if one has been set.
+    # @return [Log] the forward Log Actor if set
     def forward()
       @forward
     end
@@ -26,6 +34,14 @@ module Opee
     # Use ask() to invoke private methods. If called directly they will be
     # picked up by the Actor method_missing() method.
 
+    # Sets the logger, severity, and formatter if provided.
+    # @param [Hash] options options to be used for initialization
+    # @option options [String] :filename filename to write to
+    # @option options [Fixnum] :max_file_size maximum file size
+    # @option options [Fixnum] :max_file_count maximum number of log file
+    # @option options [IO] :stream IO stream
+    # @option options [String|Fixnum] :severity initial setting for severity
+    # @option options [Proc] :formatter initial setting for the formatter procedure
     def set_options(options)
       super(options)
       if !(filename = options[:filename]).nil?
@@ -41,11 +57,18 @@ module Opee
       formatter = options[:formatter] if options.has_key?(:formatter)
     end
 
+    # Writes a message if the severity is high enough. This method is
+    # executed asynchronously.
+    # @param [Fixnum] severity one of the Logger levels
+    # @param [String] message string to log
     def log(severity, message)
       @logger.add(severity, message)
       @forward.log(severity, message) unless @forward.nil?
     end
 
+    # Sets the logger to use the stream specified. This method is executed
+    # asynchronously.
+    # @param [IO] stream stream to write log messages to
     def stream=(stream)
       logger = Logger.new(stream)
       logger.level = @logger.level
@@ -53,6 +76,11 @@ module Opee
       @logger = logger
     end
 
+    # Creates a new Logger to write log messages to using the parameters
+    # specified. This method is executed asynchronously.
+    # @param [String] filename filename of active log file
+    # @param [Fixmun] shift_age maximum number of archive files to save
+    # @param [Fixmun] shift_size maximum file size
     def set_filename(filename, shift_age=7, shift_size=1048576)
       logger = Logger.new(filename, shift_age, shift_size)
       logger.level = @logger.level
@@ -60,14 +88,23 @@ module Opee
       @logger = logger
     end
 
+    # Replace the logger with a new Logger Object. This method is executed
+    # asynchronously.
+    # @param [Logger] logger replacement logger
     def logger=(logger)
       @logger = logger
     end
 
+    # Sets the {#forward} to the actor specified. This method is executed
+    # asynchronously.
+    # @param [Log] forward_actor Log Actor to forward log calls to
     def forward=(forward_actor)
       @forward = forward_actor
     end
 
+    # Sets the severity level of the logger. This method is executed
+    # asynchronously.
+    # @param [String|Fixnum] level value to set the severity to
     def severity=(level)
       if level.is_a?(String)
         severity = {
@@ -85,6 +122,9 @@ module Opee
       @logger.level = level
     end
 
+    # Sets the formatter procedure of the logger. This method is executed
+    # asynchronously.
+    # @param [Proc] proc value to set the formatter to
     def formatter=(proc)
       @logger.formatter = proc
     end

data/lib/opee/version.rb

@@ -1,5 +1,5 @@
 
 module Opee
   # Current version of the module. 
-  VERSION = '0.0.5'
+  VERSION = '0.1.0'
 end

data/lib/opee/workqueue.rb

@@ -1,5 +1,8 @@
 
 module Opee
+  # Implements a work queue Actor that ill distribute jobs to Actors that
+  # volunteer to complete those jobs. The primary use is to distribute work or
+  # jobs across multiple workers.
   class WorkQueue < Actor
 
     def initialize(options={})
@@ -12,18 +15,34 @@ module Opee
       super(options)
     end
 
+    # Returns the number of jobs currently on the work queue.
+    # @return [Fixnum] number of waiting jobs
     def work_queue_size()
       @work_queue.size
     end
 
+    # Returns the number of worker Actors waiting to process jobs.
+    # @return [Fixnum] number of waiting workers
     def worker_count()
       @workers.size
     end
 
+    # Returns the method invoked on the workers to process a job.
+    # @return [Symbol] method workers are asked to complete
+    def method()
+      @workers.size
+    end
+
+    # Returns the true if any requests are queued, a request is being
+    # processed, or if there are jobs waiting on the work request queue.
+    # @return [true|false] true if busy, false otherwise
     def busy?
       !@work_queue.empty? || super
     end
 
+    # Verifies that additional jobs can be added to the work queue before
+    # allowing an {#add}() to be called.
+    # @see Actor#ask
     def ask(op, *args)
       if :add == op && 0 < @max_job_count && (@work_queue.size() + @queue.size()) >= @max_job_count
         unless 0.0 >= @job_timeout
@@ -41,6 +60,13 @@ module Opee
 
     private
 
+    # Processes the initialize() options. Subclasses should call super.
+    # @param [Hash] options options to be used for initialization
+    # @option options [Symbol] :method method to call on workers
+    # @option options [Fixnum] :max_job_count maximum number of jobs
+    #         that can be queued before backpressure is applied to the caller.
+    # @option options [Float] :job_timeout timeout in seconds to wait
+    #         before raising a BusyError if the work queue is too long.
     def set_options(options)
       super(options)
       raise MissingOptionError.new(:method, "for processing jobs") if (@method = options[:method]).nil?
@@ -48,6 +74,8 @@ module Opee
       @job_timeout = options.fetch(:job_timeout, @job_timeout)
     end
 
+    # Places a job on the work queue. This method is executed asynchronously.
+    # @param [Object] job work to be processed
     def add(job)
       if @workers.empty?
         @work_queue.insert(0, job)
@@ -57,6 +85,9 @@ module Opee
       end
     end
 
+    # Identifies a worker as available to process jobs when they become
+    # available. This method is executed asynchronously.
+    # @param [Actor] worker Actor that responds to the {#method}
     def ready(worker)
       if @work_queue.empty?
         @workers.insert(0, worker) unless @workers.include?(worker)

data/test/tc_opee_collector.rb

@@ -0,0 +1,152 @@
+#!/usr/bin/env ruby -wW2
+# encoding: UTF-8
+
+[ File.dirname(__FILE__),
+  File.join(File.dirname(__FILE__), "../lib")
+].each { |path| $: << path unless $:.include?(path) }
+
+require 'test/unit'
+require 'opee'
+
+class NotJob
+  attr_reader :a, :b, :c
+
+  def initialize()
+    @a = []
+    @b = []
+    @c = []
+  end
+
+end # NotJob
+
+class NiceJob < ::Opee::Job
+  attr_reader :a, :b, :c
+
+  def initialize(next_actor)
+    @next_actor = next_actor
+    @a = []
+    @b = []
+    @c = []
+  end
+
+  def update_token(token, path_id)
+    token = [] if token.nil?
+    token << path_id
+    token
+  end
+
+  def complete?(token)
+    3 <= token.size && token.include?(:a) && token.include?(:b) && token.include?(:c)
+  end
+
+  def keep_going()
+    @next_actor.ask(:done, self)
+  end
+
+end # NiceJob
+
+class Fan < ::Opee::Actor
+  private
+
+  def set_options(options)
+    super(options)
+    @fans = options[:fans]
+  end
+
+  def go(job)
+    @fans.each { |f| f.ask(:set, job) }
+  end
+
+end # Fan
+
+class Setter < ::Opee::Actor
+  private
+
+  def set_options(options)
+    super(options)
+    @attr = options[:attr]
+    @forward = options[:forward]
+  end
+
+  def set(job)
+    job.send(@attr) << true
+    @forward.ask(:collect, job, @attr)
+  end
+
+end # Setter
+
+class Col < ::Opee::Collector
+  private
+
+  def set_options(options)
+    super(options)
+    @done = options[:done]
+  end
+
+  def job_key(job)
+    job.object_id()
+  end
+
+  def update_token(job, token, path_id)
+    token.to_i + 1
+  end
+
+  def complete?(job, token)
+    3 <= token
+  end
+
+end # Col
+
+class Done < ::Opee::Actor
+  attr_reader :finished
+
+  def initialize(options={})
+    @finished = false
+    super
+  end
+
+  private
+
+  def done(job)
+    @finished = true
+  end
+
+end # Done
+
+class OpeeTest < ::Test::Unit::TestCase
+
+  def test_opee_collector
+    done = Done.new()
+    col = Col.new(:next_actor => done, :next_method => :done)
+    a = Setter.new(:attr => :a, :forward => col)
+    b = Setter.new(:attr => :b, :forward => col)
+    c = Setter.new(:attr => :c, :forward => col)
+    fan = Fan.new(:fans => [a, b, c])
+    job = NotJob.new()
+    fan.ask(:go, job)
+    ::Opee::Env.wait_close()
+    assert_equal(true, done.finished)
+    assert_equal(0, col.cache_size)
+    assert_equal([true], job.a)
+    assert_equal([true], job.b)
+    assert_equal([true], job.c)
+  end
+
+  def test_opee_job
+    done = Done.new()
+    col = ::Opee::Collector.new()
+    a = Setter.new(:attr => :a, :forward => col)
+    b = Setter.new(:attr => :b, :forward => col)
+    c = Setter.new(:attr => :c, :forward => col)
+    fan = Fan.new(:fans => [a, b, c])
+    job = NiceJob.new(done)
+    fan.ask(:go, job)
+    ::Opee::Env.wait_close()
+    assert_equal(true, done.finished)
+    assert_equal(0, col.cache_size)
+    assert_equal([true], job.a)
+    assert_equal([true], job.b)
+    assert_equal([true], job.c)
+  end
+
+end # OpeeTest

data/test/ts_opee.rb

@@ -15,3 +15,4 @@ require 'tc_opee_actor'
 require 'tc_opee_log'
 require 'tc_opee_env'
 require 'tc_opee_workqueue'
+require 'tc_opee_collector'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opee
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-03 00:00:00.000000000 Z
+date: 2012-05-14 00:00:00.000000000 Z
 dependencies: []
 description: ! 'An experimental Object-base Parallel Evaluation Environment. '
 email: peter@ohler.com
@@ -19,14 +19,17 @@ extra_rdoc_files:
 - README.md
 files:
 - lib/opee/actor.rb
+- lib/opee/collector.rb
 - lib/opee/env.rb
 - lib/opee/errors.rb
+- lib/opee/job.rb
 - lib/opee/log.rb
 - lib/opee/version.rb
 - lib/opee/workqueue.rb
 - lib/opee.rb
 - test/relay.rb
 - test/tc_opee_actor.rb
+- test/tc_opee_collector.rb
 - test/tc_opee_env.rb
 - test/tc_opee_log.rb
 - test/tc_opee_workqueue.rb
@@ -56,8 +59,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: opee
-rubygems_version: 1.8.23
+rubygems_version: 1.8.21
 signing_key: 
 specification_version: 3
 summary: An experimental Object-base Parallel Evaluation Environment.
 test_files: []
+has_rdoc: true