From 9f836a1ed8d0ef118ae538594d0909b68100a133 Mon Sep 17 00:00:00 2001
From: Dmitry Kim <dmitry point kim at gmail point com>
Date: Thu, 30 Aug 2007 11:25:23 +0000
Subject: [PATCH] + (timer) comments + documentation

---
 lib/rbot/timer.rb | 56 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/lib/rbot/timer.rb b/lib/rbot/timer.rb
index 8939b672..dd30ab68 100644
--- a/lib/rbot/timer.rb
+++ b/lib/rbot/timer.rb
@@ -12,10 +12,34 @@
 require 'thread'
 require 'monitor'
 
+# Timer handler, manage multiple Action objects, calling them when required.
+# When the Timer is constructed, a new Thread is created to manage timed
+# delays and run Actions.
+#
+# XXX: there is no way to stop the timer currently. I'm keeping it this way
+# to weed out old Timer implementation legacy in rbot code. -jsn.
 class Timer
+
+  # class representing individual timed action
   class Action
+
+    # Time when the Action should be called next
     attr_accessor :next
 
+    # options are:
+    #   start::    Time when the Action should be run for the first time.
+    #               Repeatable Actions will be repeated after that, see
+    #               :period. One-time Actions will not (obviously)
+    #               Default: Time.now + :period
+    #   period::   How often repeatable Action should be run, in seconds.
+    #               Default: 1
+    #   blocked::  if true, Action starts as blocked (i.e. will stay dormant
+    #               until unblocked)
+    #   args::     Arguments to pass to the Action callback. Default: []
+    #   repeat::   Should the Action be called repeatedly? Default: false
+    #   code::     You can specify the Action body using &block, *or* using
+    #               this option.
+
     def initialize(options = {}, &block)
       opts = {
         :period => 1,
@@ -30,6 +54,8 @@ class Timer
       debug("added #{self}")
     end
 
+    # Provides for on-the-fly reconfiguration of the Actions
+    # Accept the same arguments as the constructor
     def configure(opts = {}, &block)
       @period = opts[:period] if opts.include? :period
       @blocked = opts[:blocked] if opts.include? :blocked
@@ -53,14 +79,17 @@ class Timer
       end
     end
 
+    # modify the Action period
     def reschedule(period, &block)
       self.configure(:period => period, &block)
     end
 
+    # blocks an Action, so it won't be run
     def block
       @blocked = true
     end
 
+    # unblocks a blocked Action
     def unblock
       @blocked = false
     end
@@ -69,6 +98,8 @@ class Timer
       @blocked
     end
 
+    # calls the Action callback, resets .next to the Time of the next call,
+    # if the Action is repeatable.
     def run(now = Time.now)
       raise 'inappropriate time to run()' unless self.next && self.next <= now
       self.next = nil
@@ -87,6 +118,7 @@ class Timer
     end
   end
 
+  # creates a new Timer and starts it.
   def initialize
     self.extend(MonitorMixin)
     @tick = self.new_cond
@@ -96,6 +128,11 @@ class Timer
     self.start
   end
 
+  # creates and installs a new Action, repeatable by default.
+  #    period:: Action period
+  #    opts::   options for Action#new, see there
+  #    block::  Action callback code
+  # returns the id of the created Action
   def add(period, opts = {}, &block)
     a = Action.new({:repeat => true, :period => period}.merge(opts), &block)
     self.synchronize do
@@ -105,15 +142,24 @@ class Timer
     return a.object_id
   end
 
+  # creates and installs a new Action, one-time by default.
+  #    period:: Action delay
+  #    opts::   options for Action#new, see there
+  #    block::  Action callback code
+  # returns the id of the created Action
   def add_once(period, opts = {}, &block)
     self.add(period, {:repeat => false}.merge(opts), &block)
   end
 
+  # blocks an existing Action
+  #    aid:: Action id, obtained previously from add() or add_once()
   def block(aid)
     debug "blocking #{aid}"
     self.synchronize { self[aid].block }
   end
 
+  # unblocks an existing blocked Action
+  #    aid:: Action id, obtained previously from add() or add_once()
   def unblock(aid)
     debug "unblocking #{aid}"
     self.synchronize do
@@ -122,6 +168,8 @@ class Timer
     end
   end
 
+  # removes an existing blocked Action
+  #    aid:: Action id, obtained previously from add() or add_once()
   def remove(aid)
     self.synchronize do
       @actions.delete(aid) # or raise "nonexistent action #{aid}"
@@ -130,6 +178,10 @@ class Timer
 
   alias :delete :remove
 
+  # Provides for on-the-fly reconfiguration of Actions
+  #    aid::   Action id, obtained previously from add() or add_once()
+  #    opts::  see Action#new
+  #   block:: (optional) new Action callback code
   def configure(aid, opts = {}, &block)
     self.synchronize do
       self[aid].configure(opts, &block)
@@ -137,6 +189,10 @@ class Timer
     end
   end
 
+  # changes Action period
+  #   aid:: Action id
+  #   period:: new period
+  #   block:: (optional) new Action callback code
   def reschedule(aid, period, &block)
     self.configure(aid, :period => period, &block)
   end
-- 
2.39.2