god 0.11.0 → 0.12.0

data/doc/intro.asciidoc

@@ -0,0 +1,20 @@
+God: The Ruby Framework for Process Management
+==============================================
+Tom Preston-Werner <tom@mojombo.com>
+
+God is an easy to configure, easy to extend monitoring framework written in
+Ruby.
+
+Keeping your server processes and tasks running should be a simple part of
+your deployment process. God aims to be the simplest, most powerful monitoring
+application available.
+
+Features
+--------
+
+* Config file is written in Ruby
+* Easily write your own custom conditions in Ruby
+* Supports both poll and event based conditions
+* Different poll conditions can have different intervals
+* Integrated notification system (write your own too!)
+* Easily control non-daemonizing scripts

data/ext/god/extconf.rb

@@ -16,7 +16,7 @@ when /bsd/i, /darwin/i
     puts "Missing 'sys/event.h' header"
     fail = true
   end
-  
+
   if fail
     puts
     puts "Events handler could not be compiled (see above error). Your god installation will not support event conditions."
@@ -31,7 +31,7 @@ when /linux/i
     puts "You may need to install a header package for your system"
     fail = true
   end
-  
+
   unless have_header('linux/connector.h') && have_header('linux/cn_proc.h')
     puts
     puts "Missing 'linux/connector.h', or 'linux/cn_proc.h' header(s)"
@@ -39,7 +39,7 @@ when /linux/i
     puts "You may need to install a header package for your system"
     fail = true
   end
-  
+
   if fail
     puts
     puts "Events handler could not be compiled (see above error). Your god installation will not support event conditions."

data/ext/god/kqueue_handler.c

@@ -31,11 +31,11 @@ kqh_event_mask(VALUE klass, VALUE sym)
   } else {
     rb_raise(rb_eNotImpError, "Event `%s` not implemented", rb_id2name(id));
   }
-  
+
   return Qnil;
 }
 
-  
+
 VALUE
 kqh_monitor_process(VALUE klass, VALUE pid, VALUE mask)
 {
@@ -43,18 +43,18 @@ kqh_monitor_process(VALUE klass, VALUE pid, VALUE mask)
   ID event;
 
   (void)event;      //!< Silence warning about unused var, should be removed?
-  
+
   u_int fflags = NUM2UINT(mask);
-  
+
   EV_SET(&new_event, FIX2UINT(pid), EVFILT_PROC,
          EV_ADD | EV_ENABLE, fflags, 0, 0);
-  
+
   if (-1 == kevent(kq, &new_event, 1, NULL, 0, NULL)) {
     rb_raise(rb_eStandardError, "%s", strerror(errno));
   }
-  
+
   num_events = NUM_EVENTS;
-  
+
   return Qnil;
 }
 
@@ -64,23 +64,23 @@ kqh_handle_events()
   int nevents, i, num_to_fetch;
   struct kevent *events;
   fd_set read_set;
-  
+
   FD_ZERO(&read_set);
   FD_SET(kq, &read_set);
-  
+
   // Don't actually run this method until we've got an event
-  rb_thread_select(kq + 1, &read_set, NULL, NULL, NULL);  
-  
+  rb_thread_select(kq + 1, &read_set, NULL, NULL, NULL);
+
   // Grabbing num_events once for thread safety
   num_to_fetch = num_events;
   events = (struct kevent*)malloc(num_to_fetch * sizeof(struct kevent));
-  
+
   if (NULL == events) {
     rb_raise(rb_eStandardError, "%s", strerror(errno));
   }
-  
+
   nevents = kevent(kq, NULL, 0, events, num_to_fetch, NULL);
-  
+
   if (-1 == nevents) {
     free(events);
     rb_raise(rb_eStandardError, "%s", strerror(errno));
@@ -93,7 +93,7 @@ kqh_handle_events()
       }
     }
   }
-  
+
   free(events);
 
   return INT2FIX(nevents);
@@ -103,17 +103,17 @@ void
 Init_kqueue_handler_ext()
 {
   kq = kqueue();
-  
+
   if (kq == -1) {
     rb_raise(rb_eStandardError, "kqueue initilization failed");
   }
-  
+
   proc_exit = rb_intern("proc_exit");
   proc_fork = rb_intern("proc_fork");
   m_call = rb_intern("call");
   m_size = rb_intern("size");
   m_deregister = rb_intern("deregister");
-  
+
   mGod = rb_const_get(rb_cObject, rb_intern("God"));
   cEventHandler = rb_const_get(mGod, rb_intern("EventHandler"));
   cKQueueHandler = rb_define_class_under(mGod, "KQueueHandler", rb_cObject);

data/ext/god/netlink_handler.c

@@ -28,42 +28,42 @@ nlh_handle_events()
   char buff[CONNECTOR_MAX_MSG_SIZE];
   struct nlmsghdr *hdr;
   struct proc_event *event;
-  
+
   VALUE extra_data;
-  
+
   fd_set fds;
-  
+
   FD_ZERO(&fds);
   FD_SET(nl_sock, &fds);
-    
+
   if (0 > rb_thread_select(nl_sock + 1, &fds, NULL, NULL, NULL)) {
     rb_raise(rb_eStandardError, "%s", strerror(errno));
   }
-  
+
   /* If there were no events detected, return */
   if (! FD_ISSET(nl_sock, &fds)) {
     return INT2FIX(0);
   }
-  
-  /* if there are events, make calls */  
+
+  /* if there are events, make calls */
   if (-1 == recv(nl_sock, buff, sizeof(buff), 0)) {
     rb_raise(rb_eStandardError, "%s", strerror(errno));
   }
-  
+
   hdr = (struct nlmsghdr *)buff;
-  
+
   if (NLMSG_ERROR == hdr->nlmsg_type) {
     rb_raise(rb_eStandardError, "%s", strerror(errno));
-  } else if (NLMSG_DONE == hdr->nlmsg_type) {    
-    
+  } else if (NLMSG_DONE == hdr->nlmsg_type) {
+
     event = (struct proc_event *)((struct cn_msg *)NLMSG_DATA(hdr))->data;
-    
+
     switch(event->what) {
       case PROC_EVENT_EXIT:
         if (Qnil == rb_funcall(cEventHandler, m_watching_pid, 1, INT2FIX(event->event_data.exit.process_pid))) {
           return INT2FIX(0);
         }
-      
+
         extra_data = rb_hash_new();
         rb_hash_aset(extra_data, ID2SYM(rb_intern("pid")), INT2FIX(event->event_data.exit.process_pid));
         rb_hash_aset(extra_data, ID2SYM(rb_intern("exit_code")), INT2FIX(event->event_data.exit.exit_code));
@@ -72,18 +72,18 @@ nlh_handle_events()
 
         rb_funcall(cEventHandler, m_call, 3, INT2FIX(event->event_data.exit.process_pid), ID2SYM(proc_exit), extra_data);
         return INT2FIX(1);
-      
+
       case PROC_EVENT_FORK:
         if (Qnil == rb_funcall(cEventHandler, m_watching_pid, 1, INT2FIX(event->event_data.fork.parent_pid))) {
           return INT2FIX(0);
         }
-        
+
         extra_data = rb_hash_new();
-        rb_hash_aset(extra_data, rb_intern("parent_pid"), INT2FIX(event->event_data.fork.parent_pid));
-        rb_hash_aset(extra_data, rb_intern("parent_thread_group_id"), INT2FIX(event->event_data.fork.parent_tgid));
-        rb_hash_aset(extra_data, rb_intern("child_pid"), INT2FIX(event->event_data.fork.child_pid));
-        rb_hash_aset(extra_data, rb_intern("child_thread_group_id"), INT2FIX(event->event_data.fork.child_tgid));
-      
+        rb_hash_aset(extra_data, ID2SYM(rb_intern("parent_pid")), INT2FIX(event->event_data.fork.parent_pid));
+        rb_hash_aset(extra_data, ID2SYM(rb_intern("parent_thread_group_id")), INT2FIX(event->event_data.fork.parent_tgid));
+        rb_hash_aset(extra_data, ID2SYM(rb_intern("child_pid")), INT2FIX(event->event_data.fork.child_pid));
+        rb_hash_aset(extra_data, ID2SYM(rb_intern("child_thread_group_id")), INT2FIX(event->event_data.fork.child_tgid));
+
         rb_funcall(cEventHandler, m_call, 3, INT2FIX(event->event_data.fork.parent_pid), ID2SYM(proc_fork), extra_data);
         return INT2FIX(1);
 
@@ -94,7 +94,7 @@ nlh_handle_events()
         break;
     }
   }
-  
+
   return Qnil;
 }
 
@@ -109,23 +109,23 @@ connect_to_netlink()
   char buff[NL_MESSAGE_SIZE];
   struct nlmsghdr *hdr; /* for telling netlink what we want */
   struct cn_msg *msg;   /* the actual connector message */
-  
+
   /* connect to netlink socket */
   nl_sock = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);
-  
+
   if (-1 == nl_sock) {
     rb_raise(rb_eStandardError, "%s", strerror(errno));
   }
-  
+
   bzero(&sa_nl, sizeof(sa_nl));
   sa_nl.nl_family = AF_NETLINK;
   sa_nl.nl_groups = CN_IDX_PROC;
   sa_nl.nl_pid    = getpid();
-  
+
   if (-1 == bind(nl_sock, (struct sockaddr *)&sa_nl, sizeof(sa_nl))) {
     rb_raise(rb_eStandardError, "%s", strerror(errno));
   }
-  
+
   /* Fill header */
   hdr = (struct nlmsghdr *)buff;
   hdr->nlmsg_len = NL_MESSAGE_SIZE;
@@ -133,7 +133,7 @@ connect_to_netlink()
   hdr->nlmsg_flags = 0;
   hdr->nlmsg_seq = 0;
   hdr->nlmsg_pid = getpid();
-  
+
   /* Fill message */
   msg = (struct cn_msg *)NLMSG_DATA(hdr);
   msg->id.idx = CN_IDX_PROC;  /* Connecting to process information */
@@ -143,7 +143,7 @@ connect_to_netlink()
   msg->flags = 0;
   msg->len = sizeof(int);
   *(int*)msg->data = PROC_CN_MCAST_LISTEN;
-  
+
   if (-1 == send(nl_sock, hdr, hdr->nlmsg_len, 0)) {
     rb_raise(rb_eStandardError, "%s", strerror(errno));
   }
@@ -151,17 +151,17 @@ connect_to_netlink()
 
 void
 Init_netlink_handler_ext()
-{ 
+{
   proc_exit = rb_intern("proc_exit");
   proc_fork = rb_intern("proc_fork");
   m_call = rb_intern("call");
   m_watching_pid = rb_intern("watching_pid?");
-  
+
   mGod = rb_const_get(rb_cObject, rb_intern("God"));
   cEventHandler = rb_const_get(mGod, rb_intern("EventHandler"));
   cNetlinkHandler = rb_define_class_under(mGod, "NetlinkHandler", rb_cObject);
   rb_define_singleton_method(cNetlinkHandler, "handle_events", nlh_handle_events, 0);
-  
+
   connect_to_netlink();
 }
 

data/god.gemspec

@@ -3,8 +3,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
 
   s.name = 'god'
-  s.version = '0.11.0'
-  s.date = '2010-07-01'
+  s.version = '0.12.0'
+  s.date = '2012-01-13'
 
   s.summary = "Process monitoring framework."
   s.description = "An easy to configure, easy to extend monitoring framework written in Ruby."
@@ -18,28 +18,35 @@ Gem::Specification.new do |s|
   s.require_paths = %w[lib ext]
 
   s.executables = ["god"]
-  s.default_executable = 'god'
   s.extensions = %w[ext/god/extconf.rb]
 
   s.rdoc_options = ["--charset=UTF-8"]
-  s.extra_rdoc_files = %w[README.txt]
+  s.extra_rdoc_files = %w[README.md]
 
-  s.add_development_dependency('twitter', [">= 0.3.7"])
-  s.add_development_dependency('prowly', [">= 0.2.1"])
-  s.add_development_dependency('xmpp4r', [">= 0.4.0"])
-  s.add_development_dependency('dike', [">= 0.0.3"])
-  s.add_development_dependency('snapshot', [">= 1.0.0", "< 2.0.0"])
-  s.add_development_dependency('rcov', [">= 0.9.8"])
-  s.add_development_dependency('daemons', [">= 1.0.10", "< 2.0.0"])
-  s.add_development_dependency('mocha', [">= 0.9.1"])
+  s.add_development_dependency('json', '~> 1.6')
+  s.add_development_dependency('rake', '~> 0.9')
+  s.add_development_dependency('rdoc', '~> 3.10')
+  s.add_development_dependency('twitter', '~> 2.0')
+  s.add_development_dependency('prowly', '~> 0.3')
+  s.add_development_dependency('xmpp4r', '~> 0.5')
+  s.add_development_dependency('dike', '~> 0.0.3')
+  s.add_development_dependency('snapshot', '~> 1.0')
+  s.add_development_dependency('rcov', '~> 0.9')
+  s.add_development_dependency('daemons', '~> 1.1')
+  s.add_development_dependency('mocha', '~> 0.10')
+  s.add_development_dependency('gollum', '~> 1.3.1')
 
   # = MANIFEST =
   s.files = %w[
     Announce.txt
+    Gemfile
     History.txt
-    README.txt
+    LICENSE
+    README.md
     Rakefile
     bin/god
+    doc/god.asciidoc
+    doc/intro.asciidoc
     ext/god/.gitignore
     ext/god/extconf.rb
     ext/god/kqueue_handler.c
@@ -67,6 +74,7 @@ Gem::Specification.new do |s|
     lib/god/conditions/memory_usage.rb
     lib/god/conditions/process_exits.rb
     lib/god/conditions/process_running.rb
+    lib/god/conditions/socket_responding.rb
     lib/god/conditions/tries.rb
     lib/god/configurable.rb
     lib/god/contact.rb
@@ -77,8 +85,6 @@ Gem::Specification.new do |s|
     lib/god/contacts/scout.rb
     lib/god/contacts/twitter.rb
     lib/god/contacts/webhook.rb
-    lib/god/dependency_graph.rb
-    lib/god/diagnostics.rb
     lib/god/driver.rb
     lib/god/errors.rb
     lib/god/event_handler.rb
@@ -115,6 +121,8 @@ Gem::Specification.new do |s|
     test/configs/daemon_polls/simple_server.rb
     test/configs/degrading_lambda/degrading_lambda.god
     test/configs/degrading_lambda/tcp_server.rb
+    test/configs/keepalive/keepalive.god
+    test/configs/keepalive/keepalive.rb
     test/configs/lifecycle/lifecycle.god
     test/configs/matias/matias.god
     test/configs/real.rb
@@ -134,9 +142,9 @@ Gem::Specification.new do |s|
     test/test_conditions_disk_usage.rb
     test/test_conditions_http_response_code.rb
     test/test_conditions_process_running.rb
+    test/test_conditions_socket_responding.rb
     test/test_conditions_tries.rb
     test/test_contact.rb
-    test/test_dependency_graph.rb
     test/test_driver.rb
     test/test_email.rb
     test/test_event_handler.rb

data/lib/god.rb

@@ -17,12 +17,12 @@ end
 require 'god/errors'
 require 'god/simple_logger'
 require 'god/logger'
+require 'god/sugar'
 
 require 'god/system/process'
 require 'god/system/portable_poller'
 require 'god/system/slash_proc_poller'
 
-require 'god/dependency_graph'
 require 'god/timeline'
 require 'god/configurable'
 
@@ -47,6 +47,7 @@ require 'god/conditions/http_response_code'
 require 'god/conditions/disk_usage'
 require 'god/conditions/complex'
 require 'god/conditions/file_mtime'
+require 'god/conditions/socket_responding'
 
 require 'god/socket'
 require 'god/driver'
@@ -59,12 +60,13 @@ require 'god/event_handler'
 require 'god/registry'
 require 'god/process'
 
-require 'god/sugar'
-
 require 'god/cli/version'
 require 'god/cli/command'
 
-require 'god/diagnostics'
+# ruby 1.8 specific configuration
+if RUBY_VERSION < '1.9'
+  $KCODE = 'u'
+end
 
 CONTACT_DEPS = { }
 CONTACT_LOAD_SUCCESS = { }
@@ -109,15 +111,15 @@ end
 
 module Kernel
   alias_method :abort_orig, :abort
-  
+
   def abort(text = nil)
     $run = false
     applog(nil, :error, text) if text
     exit(1)
   end
-  
+
   alias_method :exit_orig, :exit
-  
+
   def exit(code = 0)
     $run = false
     exit_orig(code)
@@ -131,15 +133,15 @@ class Module
         if !self.running && self.inited
           abort "God.#{arg} must be set before any Tasks are defined"
         end
-        
+
         if self.running && self.inited
           applog(nil, :warn, "God.#{arg} can't be set while god is running")
           return
         end
-        
+
         instance_variable_set(('@' + arg.to_s).intern, other)
       end
-      
+
       define_method(arg) do
         instance_variable_get(('@' + arg.to_s).intern)
       end
@@ -148,16 +150,36 @@ class Module
 end
 
 module God
-  VERSION = '0.11.0'
+  # The String version number for this package.
+  VERSION = '0.12.0'
+
+  # The Integer number of lines of backlog to keep for the logger.
   LOG_BUFFER_SIZE_DEFAULT = 100
+
+  # An Array of directory paths to be used as the default PID file directory.
+  # This list will be searched in order and the first one that has write
+  # permissions will be used.
   PID_FILE_DIRECTORY_DEFAULTS = ['/var/run/god', '~/.god/pids']
+
+  # The default Integer port number for the DRb communcations channel.
   DRB_PORT_DEFAULT = 17165
+
+  # The default Array of String IPs that will allow DRb communication access.
   DRB_ALLOW_DEFAULT = ['127.0.0.1']
+
+  # The default Symbol log level.
   LOG_LEVEL_DEFAULT = :info
+
+  # The default Integer number of seconds to wait for god to terminate when
+  # issued the quit command.
   TERMINATE_TIMEOUT_DEFAULT = 10
+
+  # The default Integer number of seconds to wait for a process to terminate.
   STOP_TIMEOUT_DEFAULT = 10
+
+  # The default String signal to send for the stop command.
   STOP_SIGNAL_DEFAULT = 'TERM'
-  
+
   class << self
     # user configurable
     safe_attr_accessor :pid,
@@ -173,7 +195,7 @@ module God
                        :socket_user,
                        :socket_group,
                        :socket_perms
-    
+
     # internal
     attr_accessor :inited,
                   :running,
@@ -186,8 +208,8 @@ module God
                   :contact_groups,
                   :main
   end
-  
-  # initialize class instance variables
+
+  # Initialize class instance variables.
   self.pid = nil
   self.host = nil
   self.port = nil
@@ -199,158 +221,150 @@ module God
   self.socket_user = nil
   self.socket_group = nil
   self.socket_perms = 0755
-  
+
   # Initialize internal data.
   #
-  # Returns nothing
+  # Returns nothing.
   def self.internal_init
-    # only do this once
+    # Only do this once.
     return if self.inited
-    
-    # variable init
+
+    # Variable init.
     self.watches = {}
     self.groups = {}
     self.pending_watches = []
     self.pending_watch_states = {}
     self.contacts = {}
     self.contact_groups = {}
-    
-    # set defaults
+
+    # Set defaults.
     self.log_buffer_size ||= LOG_BUFFER_SIZE_DEFAULT
     self.port ||= DRB_PORT_DEFAULT
     self.allow ||= DRB_ALLOW_DEFAULT
     self.log_level ||= LOG_LEVEL_DEFAULT
     self.terminate_timeout ||= TERMINATE_TIMEOUT_DEFAULT
-    
-    # additional setup
+
+    # Additional setup.
     self.setup
-    
-    # log level
+
+    # Log level.
     log_level_map = {:debug => Logger::DEBUG,
                      :info => Logger::INFO,
                      :warn => Logger::WARN,
                      :error => Logger::ERROR,
                      :fatal => Logger::FATAL}
     LOG.level = log_level_map[self.log_level]
-    
-    # init has been executed
+
+    # Init has been executed.
     self.inited = true
-    
-    # not yet running
+
+    # Not yet running.
     self.running = false
   end
-  
-  # Instantiate a new, empty Watch object and pass it to the mandatory
-  # block. The attributes of the watch will be set by the configuration
-  # file.
-  #
-  # Aborts on duplicate watch name
-  #           invalid watch
-  #           conflicting group name
+
+  # Instantiate a new, empty Watch object and pass it to the mandatory block.
+  # The attributes of the watch will be set by the configuration file. Aborts
+  # on duplicate watch name, invalid watch, or conflicting group name.
   #
-  # Returns nothing
+  # Returns nothing.
   def self.watch(&block)
     self.task(Watch, &block)
   end
-  
-  # Instantiate a new, empty Task object and yield it to the mandatory
-  # block. The attributes of the task will be set by the configuration
-  # file.
-  #
-  # Aborts on duplicate task name
-  #           invalid task
-  #           conflicting group name
+
+  # Instantiate a new, empty Task object and yield it to the mandatory block.
+  # The attributes of the task will be set by the configuration file. Aborts
+  # on duplicate task name, invalid task, or conflicting group name.
   #
-  # Returns nothing
+  # Returns nothing.
   def self.task(klass = Task)
+    # Ensure internal init has run.
     self.internal_init
-    
+
     t = klass.new
     yield(t)
-    
-    # do the post-configuration
+
+    # Do the post-configuration.
     t.prepare
-    
-    # if running, completely remove the watch (if necessary) to
-    # prepare for the reload
+
+    # If running, completely remove the watch (if necessary) to prepare for
+    # the reload
     existing_watch = self.watches[t.name]
     if self.running && existing_watch
       self.pending_watch_states[existing_watch.name] = existing_watch.state
       self.unwatch(existing_watch)
     end
-    
-    # ensure the new watch has a unique name
+
+    # Ensure the new watch has a unique name.
     if self.watches[t.name] || self.groups[t.name]
       abort "Task name '#{t.name}' already used for a Task or Group"
     end
-    
-    # ensure watch is internally valid
+
+    # Ensure watch is internally valid.
     t.valid? || abort("Task '#{t.name}' is not valid (see above)")
-    
-    # add to list of watches
+
+    # Add to list of watches.
     self.watches[t.name] = t
-    
-    # add to pending watches
+
+    # Add to pending watches.
     self.pending_watches << t
-    
-    # add to group if specified
+
+    # Add to group if specified.
     if t.group
-      # ensure group name hasn't been used for a watch already
+      # Ensure group name hasn't been used for a watch already.
       if self.watches[t.group]
         abort "Group name '#{t.group}' already used for a Task"
       end
-      
+
       self.groups[t.group] ||= []
       self.groups[t.group] << t
     end
-    
-    # register watch
+
+    # Register watch.
     t.register!
-    
-    # log
+
+    # Log.
     if self.running && existing_watch
       applog(t, :info, "#{t.name} Reloaded config")
     elsif self.running
       applog(t, :info, "#{t.name} Loaded config")
     end
   end
-  
+
   # Unmonitor and remove the given watch from god.
-  #   +watch+ is the Watch to remove
   #
-  # Returns nothing
+  # watch - The Watch to remove.
+  #
+  # Returns nothing.
   def self.unwatch(watch)
-    # unmonitor
+    # Unmonitor.
     watch.unmonitor unless watch.state == :unmonitored
-    
-    # unregister
+
+    # Unregister.
     watch.unregister!
-    
-    # remove from watches
+
+    # Remove from watches.
     self.watches.delete(watch.name)
-    
-    # remove from groups
+
+    # Remove from groups.
     if watch.group
       self.groups[watch.group].delete(watch)
     end
-    
+
     applog(watch, :info, "#{watch.name} unwatched")
   end
-  
+
   # Instantiate a new Contact of the given kind and send it to the block.
-  # Then prepare, validate, and record the Contact.
-  #   +kind+ is the contact class specifier
+  # Then prepare, validate, and record the Contact. Aborts on invalid kind,
+  # duplicate contact name, invalid contact, or conflicting group name.
   #
-  # Aborts on invalid kind
-  #           duplicate contact name
-  #           invalid contact
-  #           conflicting group name
+  # kind - The Symbol contact class specifier.
   #
-  # Returns nothing
+  # Returns nothing.
   def self.contact(kind)
+    # Ensure internal init has run.
     self.internal_init
-    
-    # verify contact has been loaded
+
+    # Verify contact has been loaded.
     if CONTACT_LOAD_SUCCESS[kind] == false
       applog(nil, :error, "A required dependency for the #{kind} contact is unavailable.")
       applog(nil, :error, "Run the following commands to install the dependencies:")
@@ -359,82 +373,79 @@ module God
       end
       abort
     end
-    
-    # create the contact
+
+    # Create the contact.
     begin
       c = Contact.generate(kind)
     rescue NoSuchContactError => e
       abort e.message
     end
-    
-    # send to block so config can set attributes
+
+    # Send to block so config can set attributes.
     yield(c) if block_given?
-    
-    # call prepare on the contact
+
+    # Call prepare on the contact.
     c.prepare
-    
-    # remove existing contacts of same name
+
+    # Remove existing contacts of same name.
     existing_contact = self.contacts[c.name]
     if self.running && existing_contact
       self.uncontact(existing_contact)
     end
-    
-    # warn and noop if the contact has been defined before
+
+    # Warn and noop if the contact has been defined before.
     if self.contacts[c.name] || self.contact_groups[c.name]
       applog(nil, :warn, "Contact name '#{c.name}' already used for a Contact or Contact Group")
       return
     end
-    
-    # abort if the Contact is invalid, the Contact will have printed
-    # out its own error messages by now
+
+    # Abort if the Contact is invalid, the Contact will have printed out its
+    # own error messages by now.
     unless Contact.valid?(c) && c.valid?
       abort "Exiting on invalid contact"
     end
-    
-    # add to list of contacts
+
+    # Add to list of contacts.
     self.contacts[c.name] = c
-    
-    # add to contact group if specified
+
+    # Add to contact group if specified.
     if c.group
-      # ensure group name hasn't been used for a contact already
+      # Ensure group name hasn't been used for a contact already.
       if self.contacts[c.group]
         abort "Contact Group name '#{c.group}' already used for a Contact"
       end
-      
+
       self.contact_groups[c.group] ||= []
       self.contact_groups[c.group] << c
     end
   end
-  
+
   # Remove the given contact from god.
-  #   +contact+ is the Contact to remove
   #
-  # Returns nothing
+  # contact - The Contact to remove.
+  #
+  # Returns nothing.
   def self.uncontact(contact)
     self.contacts.delete(contact.name)
     if contact.group
       self.contact_groups[contact.group].delete(contact)
     end
   end
-  
+
   # Control the lifecycle of the given task(s).
-  #   +name+ is the name of a task/group (String)
-  #   +command+ is the command to run (String)
-  #             one of: "start"
-  #                     "monitor"
-  #                     "restart"
-  #                     "stop"
-  #                     "unmonitor"
-  #                     "remove"
-  #
-  # Returns String[]:task_names
+  #
+  # name    - The String name of a task/group.
+  # command - The String command to run. Valid commands are:
+  #           "start", "monitor", "restart", "stop", "unmonitor", "remove".
+  #
+  # Returns an Array of String task names affected by the command.
   def self.control(name, command)
-    # get the list of items
+    # Get the list of items.
     items = Array(self.watches[name] || self.groups[name]).dup
-    
+
     jobs = []
-    
-    # do the command
+
+    # Do the command.
     case command
       when "start", "monitor"
         items.each { |w| jobs << Thread.new { w.monitor if w.state != :up } }
@@ -449,16 +460,16 @@ module God
       else
         raise InvalidCommandError.new
     end
-    
+
     jobs.each { |j| j.join }
-    
+
     items.map { |x| x.name }
   end
-  
+
   # Unmonitor and stop all tasks.
   #
-  # Returns true on success
-  #         false if all tasks could not be stopped within 10 seconds
+  # Returns true on success, false if all tasks could not be stopped within 10
+  # seconds
   def self.stop_all
     self.watches.sort.each do |name, w|
       Thread.new do
@@ -466,19 +477,19 @@ module God
         w.action(:stop) if w.alive?
       end
     end
-    
+
     terminate_timeout.times do
       return true unless self.watches.map { |name, w| w.alive? }.any?
       sleep 1
     end
-    
+
     return false
   end
-  
+
   # Force the termination of god.
-  #   * Clean up pid file if one exists
-  #   * Stop DRb service
-  #   * Hard exit using exit!
+  # * Clean up pid file if one exists
+  # * Stop DRb service
+  # * Hard exit using exit!
   #
   # Never returns because the process will no longer exist!
   def self.terminate
@@ -486,14 +497,16 @@ module God
     self.server.stop if self.server
     exit!(0)
   end
-  
+
   # Gather the status of each task.
   #
   # Examples
+  #
   #   God.status
   #   # => { 'mongrel' => :up, 'nginx' => :up }
   #
-  # Returns { String:task_name => Symbol:status, ... }
+  # Returns a Hash where the key is the String task name and the value is the
+  #   Symbol status.
   def self.status
     info = {}
     self.watches.map do |name, w|
@@ -501,12 +514,13 @@ module God
     end
     info
   end
-  
+
   # Send a signal to each task.
-  #   +name+ is the String name of the task or group
-  #   +signal+ is the signal to send. e.g. HUP, 9
   #
-  # Returns String[]:task_names
+  # name   - The String name of the task or group.
+  # signal - The String or integer signal to send. e.g. 'HUP', 9.
+  #
+  # Returns an Array of String names of the tasks affected.
   def self.signal(name, signal)
     items = Array(self.watches[name] || self.groups[name]).dup
     jobs = []
@@ -514,37 +528,50 @@ module God
     jobs.each { |j| j.join }
     items.map { |x| x.name }
   end
-  
+
   # Log lines for the given task since the specified time.
-  #   +watch_name+ is the name of the task (may be abbreviated)
-  #   +since+ is the Time since which to report log lines
   #
-  # Raises God::NoSuchWatchError if no tasks matched
+  # watch_name - The String name of the task (may be abbreviated).
+  # since      - The Time since which to report log lines.
   #
-  # Returns String:joined_log_lines
+  # Raises God::NoSuchWatchError if no tasks matched.
+  # Returns the String of newline separated log lines.
   def self.running_log(watch_name, since)
     matches = pattern_match(watch_name, self.watches.keys)
-    
+
     unless matches.first
       raise NoSuchWatchError.new
     end
-    
+
     LOG.watch_log_since(matches.first, since)
   end
-  
+
   # Load a config file into a running god instance. Rescues any exceptions
   # that the config may raise and reports these back to the caller.
-  #   +code+ is a String containing the config file
-  #   +filename+ is the filename of the config file
   #
-  # Returns [String[]:task_names, String:errors]
-  def self.running_load(code, filename)
+  # code     - The String config file contents.
+  # filename - The filename of the config file.
+  # action   - The optional String command specifying how to deal with
+  #            existing watches. Valid options are: 'stop', 'remove' or
+  #            'leave' (default).
+  #
+  # Returns a three-tuple Array [loaded_names, errors, unloaded_names] where:
+  #         loaded_names   - The Array of String task names that were loaded.
+  #         errors         - The String of error messages produced during the
+  #                          load phase. Will be a blank String if no errors
+  #                          were encountered.
+  #         unloaded_names - The Array of String task names that were unloaded
+  #                          from the system (if 'remove' or 'stop' was
+  #                          specified as the action).
+  def self.running_load(code, filename, action = nil)
     errors = ""
-    watches = []
-    
+    loaded_watches = []
+    unloaded_watches = []
+    jobs = []
+
     begin
       LOG.start_capture
-      
+
       Gem.clear_paths
       eval(code, root_binding, filename)
       self.pending_watches.each do |w|
@@ -554,39 +581,61 @@ module God
           w.monitor if w.autostart?
         end
       end
-      watches = self.pending_watches.dup
+      loaded_watches = self.pending_watches.map { |w| w.name }
       self.pending_watches.clear
       self.pending_watch_states.clear
 
-      # make sure we quit capturing when we're done
+      self.watches.each do |name, watch|
+        next if loaded_watches.include?(name)
+
+        case action
+        when 'stop'
+          jobs << Thread.new(watch) { |w| w.action(:stop); self.unwatch(w) }
+          unloaded_watches << name
+        when 'remove'
+          jobs << Thread.new(watch) { |w| self.unwatch(w) }
+          unloaded_watches << name
+        when 'leave', '', nil
+          # Do nothing
+        else
+          raise InvalidCommandError, "Unknown action: #{action}"
+        end
+      end
+
+      # Make sure we quit capturing when we're done.
       LOG.finish_capture
     rescue Exception => e
-      # don't ever let running_load take down god
+      # Don't ever let running_load take down god.
       errors << LOG.finish_capture
-      
+
       unless e.instance_of?(SystemExit)
         errors << e.message << "\n"
         errors << e.backtrace.join("\n")
       end
     end
-    
-    names = watches.map { |x| x.name }
-    [names, errors]
+
+    jobs.each { |t| t.join }
+
+    [loaded_watches, errors, unloaded_watches]
   end
-  
+
   # Load the given file(s) according to the given glob.
-  #   +glob+ is the glob-enabled path to load
   #
-  # Returns nothing
+  # glob - The glob-enabled String path to load.
+  #
+  # Returns nothing.
   def self.load(glob)
     Dir[glob].each do |f|
       Kernel.load f
     end
   end
-  
+
+  # Setup pid file directory and log system.
+  #
+  # Returns nothing.
   def self.setup
     if self.pid_file_directory
-      # pid file dir was specified, ensure it is created and writable
+      # Pid file dir was specified, ensure it is created and writable.
       unless File.exist?(self.pid_file_directory)
         begin
           FileUtils.mkdir_p(self.pid_file_directory)
@@ -594,12 +643,12 @@ module God
           abort "Failed to create pid file directory: #{e.message}"
         end
       end
-      
+
       unless File.writable?(self.pid_file_directory)
         abort "The pid file directory (#{self.pid_file_directory}) is not writable by #{Etc.getlogin}"
       end
     else
-      # no pid file dir specified, try defaults
+      # No pid file dir specified, try defaults.
       PID_FILE_DIRECTORY_DEFAULTS.each do |idir|
         dir = File.expand_path(idir)
         begin
@@ -611,69 +660,77 @@ module God
         rescue Errno::EACCES => e
         end
       end
-      
+
       unless self.pid_file_directory
         dirs = PID_FILE_DIRECTORY_DEFAULTS.map { |x| File.expand_path(x) }
         abort "No pid file directory exists, could be created, or is writable at any of #{dirs.join(', ')}"
       end
     end
-    
+
     if God::Logger.syslog
       LOG.info("Syslog enabled.")
     else
       LOG.info("Syslog disabled.")
     end
-    
+
     applog(nil, :info, "Using pid file directory: #{self.pid_file_directory}")
   end
-  
+
   # Initialize and startup the machinery that makes god work.
   #
-  # Returns nothing
+  # Returns nothing.
   def self.start
     self.internal_init
-    
-    # instantiate server
+
+    # Instantiate server.
     self.server = Socket.new(self.port, self.socket_user, self.socket_group, self.socket_perms)
-    
-    # start monitoring any watches set to autostart
+
+    # Start monitoring any watches set to autostart.
     self.watches.values.each { |w| w.monitor if w.autostart? }
-    
-    # clear pending watches
+
+    # Clear pending watches.
     self.pending_watches.clear
-    
-    # mark as running
+
+    # Mark as running.
     self.running = true
-    
-    # don't exit
-    self.main = 
+
+    # Don't exit.
+    self.main =
     Thread.new do
       loop do
         sleep 60
       end
     end
-    
-    self.main.join
   end
-  
+
+  # Prevent god from exiting.
+  #
+  # Returns nothing.
+  def self.join
+    self.main.join if self.main
+  end
+
+  # Returns the version String.
   def self.version
     God::VERSION
   end
-  
-  # To be called on program exit to start god
+
+  # To be called on program exit to start god.
   #
-  # Returns nothing
+  # Returns nothing.
   def self.at_exit
     self.start
+    self.join
   end
-  
+
   # private
-  
+
   # Match a shortened pattern against a list of String candidates.
-  # The pattern is expanded into a regular expression by
+  # The pattern is expanded into a regular expression by 
   # inserting .* between each character.
-  #   +pattern+ is the String containing the abbreviation
-  #   +list+ is the Array of Strings to match against
+  #
+  # pattern - The String containing the abbreviation.
+  # list    - The Array of Strings to match against.
   #
   # Examples
   #
@@ -682,10 +739,10 @@ module God
   #   God.pattern_match(list, pattern)
   #   # => ['bar', 'bars']
   #
-  # Returns String[]:matched_elements
+  # Returns the Array of matching name Strings.
   def self.pattern_match(pattern, list)
     regex = pattern.split('').join('.*')
-    
+
     list.select do |item|
       item =~ Regexp.new(regex)
     end.sort_by { |x| x.size }
@@ -695,7 +752,7 @@ end
 # Runs immediately before the program exits. If $run is true,
 # start god, if $run is false, exit normally.
 #
-# Returns nothing
+# Returns nothing.
 at_exit do
   God.at_exit if $run
 end