god 0.11.0 → 0.12.0

data/lib/god/contacts/email.rb

@@ -10,10 +10,13 @@
 # === SMTP Options (when delivery_method = :smtp) ===
 # server_host     - The String hostname of the SMTP server (default: localhost).
 # server_port     - The Integer port of the SMTP server (default: 25).
-# server_auth     - The Boolean of whether or not to use authentication
-#                   (default: false).
+# server_auth     - The Symbol authentication method. Possible values:
+#                   [ nil | :plain | :login | :cram_md5 ]
+#                   The default is nil, which means no authentication. To
+#                   enable authentication, pass the appropriate symbol and
+#                   then pass the appropriate SMTP Auth Options (below).
 #
-# === SMTP Auth Options (when server_auth = true) ===
+# === SMTP Auth Options (when server_auth != nil) ===
 # server_domain   - The String domain.
 # server_user     - The String username.
 # server_password - The String password.
@@ -41,7 +44,7 @@ module God
       self.from_email = 'god@example.com'
       self.from_name = 'God Process Monitoring'
       self.delivery_method = :smtp
-      self.server_auth = false
+      self.server_auth = nil
       self.server_host = 'localhost'
       self.server_port = 25
       self.sendmail_path = '/usr/sbin/sendmail'

data/lib/god/contacts/jabber.rb

@@ -72,4 +72,4 @@ module God
 
     end
   end
-end
+end

data/lib/god/driver.rb

@@ -1,78 +1,107 @@
 require 'monitor'
 
-# ruby 1.9 specific fixes
+# Ruby 1.9 specific fixes.
 unless RUBY_VERSION < '1.9'
   require 'god/compat19'
 end
 
 module God
+  # The TimedEvent class represents an event in the future. This class is used
+  # by the drivers to schedule upcoming conditional tests and other scheduled
+  # events.
   class TimedEvent
     include Comparable
 
+    # The Time at which this event is due.
     attr_accessor :at
-    
-    # Instantiate a new TimedEvent that will be triggered after the specified delay
-    #   +delay+ is the number of seconds from now at which to trigger
+
+    # Instantiate a new TimedEvent that will be triggered after the specified
+    # delay.
     #
-    # Returns TimedEvent
+    # delay - The optional Numeric number of seconds from now at which to
+    #         trigger (default: 0).
     def initialize(delay = 0)
       self.at = Time.now + delay
     end
 
+    # Is the current event due (current time >= event time)?
+    #
+    # Returns true if the event is due, false if not.
     def due?
       Time.now >= self.at
     end
 
+    # Compare this event to another.
+    #
+    # other - The other TimedEvent.
+    #
+    # Returns -1 if this event is before the other, 0 if the two events are
+    #   due at the same time, 1 if the other event is later.
     def <=>(other)
       self.at <=> other.at
     end
-  end # DriverEvent
+  end
 
+  # A DriverEvent is a TimedEvent with an associated Task and Condition. This
+  # is the primary mechanism for poll conditions to be scheduled.
   class DriverEvent < TimedEvent
-    attr_accessor :condition, :task
-    
+    # Initialize a new DriverEvent.
+    #
+    # delay     - The Numeric delay for this event.
+    # task      - The Task associated with this event.
+    # condition - The Condition associated with this event.
     def initialize(delay, task, condition)
-      super delay
-      self.task = task
-      self.condition = condition
+      super(delay)
+      @task = task
+      @condition = condition
     end
-    
+
+    # Handle this event by invoking the underlying condition on the associated
+    # task.
+    #
+    # Returns nothing.
     def handle_event
       @task.handle_poll(@condition)
     end
-  end # DriverEvent
+  end
 
+  # A DriverOperation is a TimedEvent that is due as soon as possible. It is
+  # used to execute an arbitrary method on the associated Task.
   class DriverOperation < TimedEvent
-    attr_accessor :task, :name, :args
-
+    # Initialize a new DriverOperation.
+    #
+    # task - The Task upon which to operate.
+    # name - The Symbol name of the method to call.
+    # args - The Array of arguments to send to the method.
     def initialize(task, name, args)
       super(0)
-      self.task = task
-      self.name = name
-      self.args = args
+      @task = task
+      @name = name
+      @args = args
     end
-    
-    # Handle the next queued operation that was issued asynchronously
+
+    # Handle the operation that was issued asynchronously.
     #
-    # Returns nothing
+    # Returns nothing.
     def handle_event
       @task.send(@name, *@args)
     end
   end
 
+  # The DriverEventQueue is a simple queue that holds TimedEvent instances in
+  # order to maintain the schedule of upcoming events.
   class DriverEventQueue
+    # Initialize a DriverEventQueue.
     def initialize
       @shutdown = false
       @events = []
       @monitor = Monitor.new
       @resource = @monitor.new_cond
-      @events.taint
-      self.taint
     end
 
+    # Wake any sleeping threads after setting the sentinel.
     #
-    # Wake any sleeping threads after setting the sentinel
-    #
+    # Returns nothing.
     def shutdown
       @shutdown = true
       @monitor.synchronize do
@@ -80,15 +109,16 @@ module God
       end
     end
 
+    # Wait until the queue has something due, pop it off the queue, and return
+    # it.
     #
-    # Sleep until the queue has something due
-    #
+    # Returns the popped event.
     def pop
       @monitor.synchronize do
         if @events.empty?
           raise ThreadError, "queue empty" if @shutdown
           @resource.wait
-        else !@events.first.due?
+        else
           delay = @events.first.at - Time.now
           @resource.wait(delay) if delay > 0
         end
@@ -97,35 +127,34 @@ module God
       end
     end
 
-    alias shift pop
-    alias deq pop
-
-    #
     # Add an event to the queue, wake any waiters if what we added needs to
-    # happen sooner than the next pending event
+    # happen sooner than the next pending event.
     #
+    # Returns nothing.
     def push(event)
       @monitor.synchronize do
         @events << event
         @events.sort!
 
         # If we've sorted the events and found the one we're adding is at
-        # the front, it will likely need to run before the next due date
+        # the front, it will likely need to run before the next due date.
         @resource.signal if @events.first == event
       end
     end
 
-    alias << push
-    alias enq push
-
+    # Returns true if the queue is empty, false if not.
     def empty?
       @events.empty?
     end
 
+    # Clear the queue.
+    #
+    # Returns nothing.
     def clear
       @events.clear
     end
 
+    # Returns the Integer length of the queue.
     def length
       @events.length
     end
@@ -133,18 +162,19 @@ module God
     alias size length
   end
 
-
+  # The Driver class is responsible for scheduling all of the events for a
+  # given Task.
   class Driver
+    # The Thread running the driver loop.
     attr_reader :thread
 
-    # Instantiate a new Driver and start the scheduler loop to handle events
-    #   +task+ is the Task this Driver belongs to
+    # Instantiate a new Driver and start the scheduler loop to handle events.
     #
-    # Returns Driver
+    # task - The Task this Driver belongs to.
     def initialize(task)
       @task = task
       @events = God::DriverEventQueue.new
-      
+
       @thread = Thread.new do
         loop do
           begin
@@ -160,47 +190,49 @@ module God
         end
       end
     end
-    
-    # Check if we're in the driver context
+
+    # Check if we're in the driver context.
     #
-    # Returns true if in driver thread
+    # Returns true if in driver thread, false if not.
     def in_driver_context?
       Thread.current == @thread
     end
 
-    # Clear all events for this Driver
-    # 
-    # Returns nothing
+    # Clear all events for this Driver.
+    #
+    # Returns nothing.
     def clear_events
       @events.clear
     end
 
-    # Shutdown the DriverEventQueue threads
+    # Shutdown the DriverEventQueue threads.
     #
-    # Returns nothing
+    # Returns nothing.
     def shutdown
       @events.shutdown
     end
-    
-    # Queue an asynchronous message
-    #   +name+ is the Symbol name of the operation
-    #   +args+ is an optional Array of arguments
+
+    # Queue an asynchronous message.
+    #
+    # name - The Symbol name of the operation.
+    # args - An optional Array of arguments.
     #
-    # Returns nothing
+    # Returns nothing.
     def message(name, args = [])
       @events.push(DriverOperation.new(@task, name, args))
     end
-    
-    # Create and schedule a new DriverEvent
-    #   +condition+ is the Condition
-    #   +delay+ is the number of seconds to delay (default: interval defined in condition)
+
+    # Create and schedule a new DriverEvent.
+    #
+    # condition - The Condition.
+    # delay     - The Numeric number of seconds to delay (default: interval
+    #             defined in condition).
     #
-    # Returns nothing
+    # Returns nothing.
     def schedule(condition, delay = condition.interval)
       applog(nil, :debug, "driver schedule #{condition} in #{delay} seconds")
-      
+
       @events.push(DriverEvent.new(delay, @task, condition))
     end
-  end # Driver
-  
-end # God
+  end
+end

data/lib/god/errors.rb

@@ -1,24 +1,24 @@
 module God
-  
+
   class AbstractMethodNotOverriddenError < StandardError
   end
-  
+
   class NoSuchWatchError < StandardError
   end
-  
+
   class NoSuchConditionError < StandardError
   end
-  
+
   class NoSuchBehaviorError < StandardError
   end
-  
+
   class NoSuchContactError < StandardError
   end
-  
+
   class InvalidCommandError < StandardError
   end
-  
+
   class EventRegistrationFailedError < StandardError
   end
-  
-end
+
+end

data/lib/god/event_handler.rb

@@ -3,15 +3,15 @@ module God
     @@actions = {}
     @@handler = nil
     @@loaded = false
-    
+
     def self.loaded?
       @@loaded
     end
-    
+
     def self.event_system
       @@handler::EVENT_SYSTEM
     end
-    
+
     def self.load
       begin
         case RUBY_PLATFORM
@@ -31,13 +31,13 @@ module God
         @@loaded = false
       end
     end
-    
+
     def self.register(pid, event, &block)
       @@actions[pid] ||= {}
       @@actions[pid][event] = block
       @@handler.register_process(pid, @@actions[pid].keys)
     end
-    
+
     def self.deregister(pid, event)
       if watching_pid? pid
         running = ::Process.kill(0, pid.to_i) rescue false
@@ -46,15 +46,15 @@ module God
         @@actions.delete(pid) if @@actions[pid].empty?
       end
     end
-    
+
     def self.call(pid, event, extra_data = {})
       @@actions[pid][event].call(extra_data) if watching_pid?(pid) && @@actions[pid][event]
     end
-    
+
     def self.watching_pid?(pid)
       @@actions[pid]
     end
-    
+
     def self.start
       Thread.new do
         loop do
@@ -67,42 +67,42 @@ module God
           end
         end
       end
-      
+
       # do a real test to make sure events are working properly
       @@loaded = self.operational?
     end
-    
+
     def self.operational?
       com = [false]
-      
+
       Thread.new do
         begin
           event_system = God::EventHandler.event_system
-          
+
           pid = fork do
             loop { sleep(1) }
           end
-          
+
           self.register(pid, :proc_exit) do
             com[0] = true
           end
-          
+
           ::Process.kill('KILL', pid)
           ::Process.waitpid(pid)
-          
+
           sleep(0.1)
-          
+
           self.deregister(pid, :proc_exit) rescue nil
         rescue => e
           puts e.message
           puts e.backtrace.join("\n")
         end
       end.join
-      
+
       sleep(0.1)
-      
+
       com.first
     end
-    
+
   end
 end