From 1c25d7c73c4a648516477f57ae13b0a1408e367c Mon Sep 17 00:00:00 2001 From: Nick Gauthier Date: Fri, 29 Jan 2010 13:21:09 -0500 Subject: [PATCH] Documentation --- lib/hydra/master.rb | 13 ++++++++++++- lib/hydra/message/runner_messages.rb | 9 ++++++--- lib/hydra/message/worker_messages.rb | 14 +++++++------- lib/hydra/messaging_io.rb | 1 + lib/hydra/runner.rb | 8 +++++++- lib/hydra/worker.rb | 6 ++++++ 6 files changed, 39 insertions(+), 12 deletions(-) diff --git a/lib/hydra/master.rb b/lib/hydra/master.rb index 5621c39..9ab6f70 100644 --- a/lib/hydra/master.rb +++ b/lib/hydra/master.rb @@ -1,5 +1,15 @@ module Hydra #:nodoc: + # Hydra class responsible for delegate work down to workers. + # + # The Master is run once for any given testing session. class Master + # Create a new Master + # + # Options: + # * :files + # * An array of test files to be run. These should be relative paths from + # the root of the project, since they may be run on different machines + # which may have different paths. def initialize(opts = { }) @files = opts.fetch(:files) { [] } @workers = [] @@ -10,7 +20,8 @@ module Hydra #:nodoc: # Message handling - # Send a file down to a worker + # Send a file down to a worker. If there are no more files, this will shut the + # worker down. def send_file(worker) f = @files.pop if f diff --git a/lib/hydra/message/runner_messages.rb b/lib/hydra/message/runner_messages.rb index 6aec99a..1c739c9 100644 --- a/lib/hydra/message/runner_messages.rb +++ b/lib/hydra/message/runner_messages.rb @@ -11,6 +11,7 @@ module Hydra #:nodoc: # Message telling the Runner to run a file # TODO: move to worker class RunFile < Hydra::Message + # The file that should be run attr_accessor :file def serialize #:nodoc: super(:file => @file) @@ -22,7 +23,9 @@ module Hydra #:nodoc: # Message for the Runner to respond with its results class Results < Hydra::Message + # The output from running the test attr_accessor :output + # The file that was run attr_accessor :file def serialize #:nodoc: super(:output => @output, :file => @file) @@ -42,9 +45,9 @@ module Hydra #:nodoc: # Message a runner sends to a worker to verify the connection class Ping < Hydra::Message - # We don't do anything to handle a ping. It's just to test - # the connectivity of the IO - def handle(worker, runner) + def handle(worker, runner) #:nodoc: + # We don't do anything to handle a ping. It's just to test + # the connectivity of the IO end end end diff --git a/lib/hydra/message/worker_messages.rb b/lib/hydra/message/worker_messages.rb index 04bd1e1..988ae31 100644 --- a/lib/hydra/message/worker_messages.rb +++ b/lib/hydra/message/worker_messages.rb @@ -3,7 +3,7 @@ module Hydra #:nodoc: module Worker #:nodoc: # Message indicating that a worker needs a file to delegate to a runner class RequestFile < Hydra::Message - def handle(master, worker) + def handle(master, worker) #:nodoc: master.send_file(worker) end end @@ -11,14 +11,14 @@ module Hydra #:nodoc: # Message telling a worker to delegate a file to a runner # TODO: move to master messages class RunFile < Hydra::Messages::Runner::RunFile - def handle(worker) + def handle(worker) #:nodoc: worker.delegate_file(self) end end # Message relaying the results of a worker up to the master class Results < Hydra::Messages::Runner::Results - def handle(master, worker) + def handle(master, worker) #:nodoc: master.send_file(worker) end end @@ -26,16 +26,16 @@ module Hydra #:nodoc: # Message telling the worker to shut down. # TODO: move to master class Shutdown < Hydra::Messages::Runner::Shutdown - def handle(worker) + def handle(worker) #:nodoc: worker.shutdown end end # Message a worker sends to a master to verify the connection class Ping < Hydra::Message - # We don't do anything to handle a ping. It's just to test - # the connectivity of the IO - def handle(master, worker) + def handle(master, worker) #:nodoc: + # We don't do anything to handle a ping. It's just to test + # the connectivity of the IO end end end diff --git a/lib/hydra/messaging_io.rb b/lib/hydra/messaging_io.rb index 731c3a4..551826d 100644 --- a/lib/hydra/messaging_io.rb +++ b/lib/hydra/messaging_io.rb @@ -37,6 +37,7 @@ module Hydra #:nodoc: # For example, if you tried to write a string, it would fail, # because the string is not a message. class UnprocessableMessage < RuntimeError + # Custom error message attr_accessor :message end end diff --git a/lib/hydra/runner.rb b/lib/hydra/runner.rb index cbeecbf..17bb843 100644 --- a/lib/hydra/runner.rb +++ b/lib/hydra/runner.rb @@ -1,5 +1,11 @@ module Hydra #:nodoc: - # Hydra class responsible for running test files + # Hydra class responsible for running test files. + # + # The Runner is never run directly by a user. Runners are created by a + # Worker to run test files. + # + # The general convention is to have one Runner for each logical processor + # of a machine. class Runner # Boot up a runner. It takes an IO object (generally a pipe from its # parent) to send it messages on which files to execute. diff --git a/lib/hydra/worker.rb b/lib/hydra/worker.rb index 5ebc62c..b8ccdd2 100644 --- a/lib/hydra/worker.rb +++ b/lib/hydra/worker.rb @@ -1,5 +1,11 @@ module Hydra #:nodoc: # Hydra class responsible to dispatching runners and communicating with the master. + # + # The Worker is never run directly by a user. Workers are created by a + # Master to delegate to Runners. + # + # The general convention is to have one Worker per machine on a distributed + # network. class Worker # Create a new worker. # * io: The IO object to use to communicate with the master