ActionTimer 0.0.1 → 0.0.2

data/CHANGELOG

@@ -0,0 +1,7 @@
+= CHANGELOG
+
+== 0.0.2
+* added new Timer::running? method
+* added new Timer::pause method
+* fixed single iteration action bug
+* added unit tests for proper checks

data/README.rdoc

@@ -0,0 +1,46 @@
+== ActionTimer: Simple timing for a complex world
+
+ActionTimer is a helper for timed events. It allows for single and recurring actions to be executed in an efficient manner. It makes use of a single thread to keep time on registered actions and uses an ActionPool to execute actions. Simple and effective.
+
+==== useful links
+* {trac site}[http://dev.modspox.com/trac/actiontimer]
+* {RDocs}[http://dev.modspox.com/~sine/ActionTimer]
+
+=== install (easy):
+
+    gem install --include-dependencies ActionTimer
+
+=== install (less easy):
+
+    git clone http://github.com/spox/actiontimer.git
+    cd actiontimer
+    gem build actiontimer.gemspec
+    gem install ActionTimer-x.x.x.gem
+
+=== Simple example of using the timer:
+
+    require 'actiontimer'
+
+    timer = ActionTimer::Timer.new
+
+    timer.add(10){puts "#{Time.now}: This is timed every 10 seconds"}
+    timer.add(15){puts "#{Time.now}: This is timed every 15 seconds"}
+    loop do
+        puts "#{Time.now}: Main loop that sleeps for 5 seconds"
+        sleep(5)
+    end
+
+==== Output:
+
+    2009-04-13 17:41:39 -0700: Main loop that sleeps for 5 seconds
+    2009-04-13 17:41:44 -0700: Main loop that sleeps for 5 seconds
+    2009-04-13 17:41:49 -0700: This is timed every 10 seconds
+    2009-04-13 17:41:49 -0700: Main loop that sleeps for 5 seconds
+    2009-04-13 17:41:54 -0700: This is timed every 15 seconds
+    2009-04-13 17:41:54 -0700: Main loop that sleeps for 5 seconds
+    2009-04-13 17:41:59 -0700: This is timed every 10 seconds
+    2009-04-13 17:41:59 -0700: Main loop that sleeps for 5 seconds
+    2009-04-13 17:42:04 -0700: Main loop that sleeps for 5 seconds
+    2009-04-13 17:42:09 -0700: This is timed every 10 seconds
+    2009-04-13 17:42:09 -0700: This is timed every 15 seconds
+    2009-04-13 17:42:09 -0700: Main loop that sleeps for 5 seconds

data/actiontimer.gemspec

@@ -2,12 +2,24 @@ spec = Gem::Specification.new do |s|
     s.name              = 'ActionTimer'
     s.author            = %q(spox)
     s.email             = %q(spox@modspox.com)
-    s.version           = '0.0.1'
+    s.version           = '0.0.2'
     s.summary           = %q(Simple timer for a complex world)
     s.platform          = Gem::Platform::RUBY
     s.has_rdoc          = true
+    s.rdoc_options      = %w(--title ActionTimer --main README.rdoc --line-numbers --inline-source)
+    s.extra_rdoc_files  = %w(README.rdoc LICENSE CHANGELOG)
     s.files             = Dir['**/*']
     s.require_paths     = %w(lib)
     s.add_dependency 'ActionPool'
     s.required_ruby_version = '>= 1.8.6'
+    s.homepage          = %q(http://dev.modspox.com/trac/ActionTimer)
+    description         = []
+    File.open("README.rdoc") do |file|
+        file.each do |line|
+            line.chomp!
+            break if line.empty?
+            description << "#{line.gsub(/\[\d\]/, '')}"
+        end
+    end
+    s.description = description[1..-1].join(" ")
 end

data/lib/actiontimer/Timer.rb

@@ -5,20 +5,29 @@ module ActionTimer
     class Timer
         # pool:: ActionPool for processing actions
         # Creates a new timer
-        def initialize(pool=nil, logger=nil)
+        # Argument hash: {:pool, :logger, :auto_start}
+        def initialize(args={}, extra=nil)
+            auto_start = true
+            if(args.is_a?(Hash))
+                @pool = args[:pool] ? args[:pool] : ActionPool::Pool.new
+                @logger = LogHelper.new(args[:logger])
+                auto_start = args.has_key?(:auto_start) ? args[:auto_start] : true
+            else
+                @pool = args.is_a?(ActionPool::Pool) ? args : ActionPool::Pool.new
+                @logger = LogHelper.new(extra)
+            end
             @actions = []
             @new_actions = []
             @timer_thread = nil
             @stop_timer = false
             @add_lock = Mutex.new
             @awake_lock = Mutex.new
-            @pool = pool.nil? ? ActionPool::Pool.new : pool
-            @logger = LogHelper.new(logger)
-            start
+            start if auto_start
         end
         
         # Forcibly wakes the timer early
         def wakeup
+            raise NotRunning.new unless running?
             return unless @awake_lock.try_lock
             @timer_thread.wakeup if @timer_thread.status == 'sleep'
             @awake_lock.unlock
@@ -34,7 +43,7 @@ module ActionTimer
             action = Action.new(self, period, once, data, &func)
             action.owner = owner unless owner.nil?
             @add_lock.synchronize{ @new_actions << action }
-            wakeup
+            wakeup if running?
             return action
         end
         
@@ -46,7 +55,7 @@ module ActionTimer
                 raise InvalidType.new(ActionTimer::Action, action.class) unless action.is_a?(Action)
             end
             @add_lock.synchronize{ @new_actions = @new_actions + actions }
-            wakeup
+            wakeup if running?
         end
         
         # action:: Action to remove from timer
@@ -54,12 +63,13 @@ module ActionTimer
         def remove(action)
             raise InvalidType.new(ActionTimer::Action, action.class) unless action.is_a?(Action)
             @actions.delete(action)
-            wakeup
+            wakeup if running?
         end
         
         # Start the timer
         def start
             raise AlreadyRunning.new unless @timer_thread.nil?
+            @stop_timer = false
             @timer_thread = Thread.new do
                 begin
                     until @stop_timer do
@@ -75,16 +85,33 @@ module ActionTimer
                         add_waiting_actions
                     end
                 rescue Object => boom
+                    @timer_thread = nil
+                    clean_actions
                     @logger.fatal("Timer encountered an unexpected error: #{boom}\n#{boom.backtrace.join("\n")}")
                 end
             end
         end
         
-        # Stop the timer
+        # Pause the timer in its current state.
+        def pause
+            @stop_timer = true
+            if(running?)
+                wakeup
+                @timer_thread.join
+            end
+            @timer_thread = nil
+        end
+
+        # Stop the timer. Unlike pause, this will completely
+        # stop the timer and remove all actions from the timer
         def stop
             @stop_timer = true
-            wakeup
-            @timer_thread.join
+            if(running?)
+                wakeup
+                clean_actions
+                @timer_thread.join
+            end
+            @timer_thread = nil
         end
         
         # owner:: owner actions to remove
@@ -100,6 +127,11 @@ module ActionTimer
             wakeup
         end
         
+        # Is timer currently running?
+        def running?
+            return !@timer_thread.nil?
+        end
+        
         private
         
         def get_min_sleep
@@ -122,7 +154,7 @@ module ActionTimer
             @actions.each do |action|
                 action.tick(time_passed)
                 if(action.due?)
-                    remove(action) if action.is_complete?
+                    @actions.delete(action) if action.is_complete?
                     action = action.schedule
                     @pool.process do
                         begin
@@ -135,5 +167,10 @@ module ActionTimer
             end
         end
         
+        def clean_actions
+            @actions.clear
+            @new_actions.clear
+        end
+        
     end
 end

data/tests/run_tests.rb

@@ -0,0 +1,129 @@
+require 'test/unit'
+require 'actiontimer'
+
+class TimerTests < Test::Unit::TestCase
+    def setup
+        @timer = ActionTimer::Timer.new
+    end
+
+    # Simple test of basic repetitive action
+    def test_basic
+        result = 0
+        @timer.add(2){ result += 1 }
+        sleep(5)
+        assert_equal(2, result)
+    end
+
+    # Check the the running? method properly reports
+    def test_running
+        @timer.add(1){ 1 + 1}
+        assert(@timer.running?)
+        @timer.pause
+        assert(!@timer.running?)
+        @timer.start
+        assert(@timer.running?)
+        @timer.stop
+        assert(!@timer.running?)
+    end
+
+    # Check that a single iterative action is only
+    # completed once
+    def test_once
+        result = 0
+        @timer.add(1, true){ result += 1 }
+        sleep(3)
+        assert_equal(1, result)
+    end
+
+    # Check that timer can be paused and restarted
+    # without registered actions being effected
+    def test_pause
+        result = 0
+        @timer.add(1){ result += 1 }
+        sleep(3.1)
+        @timer.pause
+        sleep(2)
+        @timer.start
+        sleep(2.1)
+        assert_equal(5, result)
+    end
+
+    # Check that data can be passed to the block
+    # properly when created
+    def test_data
+        result = 0
+        @timer.add(1, true, 3){|a| result = a}
+        sleep(2)
+        assert_equal(3, result)
+    end
+
+    # Check that the timer's auto starting mechanism
+    # can be disabled
+    def test_auto_start
+        timer = ActionTimer::Timer.new(:auto_start => false)
+        timer.add(1){ 1+1 }
+        assert(!timer.running?)
+        timer.start
+        assert(timer.running?)
+    end
+
+    # Check that the actions can be cleared out of the
+    # timer and the timer is still left in a "running"
+    # state.
+    def test_clear
+        result = 0
+        @timer.add(1){ result += 1 }
+        sleep(3)
+        @timer.clear
+        sleep(2)
+        assert_equal(2, result)
+        assert(@timer.running?)
+    end
+
+    # Check that the timer throws an exception when it
+    # is instructed to wakeup while not running
+    def test_wakeup
+        @timer.stop
+        assert_raise(ActionTimer::NotRunning){ @timer.wakeup }
+    end
+
+    # Check that the timer throws an exception when it
+    # is instructed to start but is already running
+    def test_start
+        assert_raise(ActionTimer::AlreadyRunning){ @timer.start }
+    end
+
+    # Check that multiple actions can be added at once
+    def test_mass_add
+        result = 0
+        actions = []
+        actions << ActionTimer::Action.new(@timer, 1){ result += 1}
+        actions << ActionTimer::Action.new(@timer, 3){ result += 1}
+        actions << ActionTimer::Action.new(@timer, 5){ result += 1}
+        @timer.mass_add(actions)
+        sleep(5.3)
+        assert_equal(7, result)
+    end
+
+    # Check that an action can be properly removed from
+    # the timer
+    def test_remove
+        result = 0
+        action = @timer.add(1){result += 1}
+        sleep(2.1)
+        @timer.remove(action)
+        sleep(2)
+        assert_equal(2, result)
+    end
+
+    # Check that an action's period can be dynamically
+    # reset
+    def test_action_reset
+        result = 0
+        action = @timer.add(1){ result += 1}
+        sleep(2.1)
+        action.reset_period(3)
+        sleep(3.1)
+        assert_equal(result, 3)
+    end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ActionTimer
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - spox
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-15 00:00:00 -07:00
+date: 2009-05-20 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -22,34 +22,40 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
     version: 
-description: 
+description: ""
 email: spox@modspox.com
 executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- README.rdoc
+- LICENSE
+- CHANGELOG
 files: 
-- README~
+- tests
+- tests/run_tests.rb
 - actiontimer.gemspec
+- README.rdoc
 - lib
 - lib/actiontimer
 - lib/actiontimer/Action.rb
 - lib/actiontimer/LogHelper.rb
 - lib/actiontimer/Exceptions.rb
-- lib/actiontimer/Action.rb~
-- lib/actiontimer/Timer.rb~
 - lib/actiontimer/Timer.rb
 - lib/actiontimer.rb
 - LICENSE
-- README
-- ActionTimer-0.0.1.gem
+- CHANGELOG
 has_rdoc: true
-homepage: 
+homepage: http://dev.modspox.com/trac/ActionTimer
 post_install_message: 
-rdoc_options: []
-
+rdoc_options: 
+- --title
+- ActionTimer
+- --main
+- README.rdoc
+- --line-numbers
+- --inline-source
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 

data/README

@@ -1,48 +0,0 @@
-            == ActionTimer ==
-  ~ Simple timing for a complex world ~
-
-ActionTimer is a helper for timed events. It
-allows for single and recurring actions to
-be executed in an efficient manner. It makes
-use of a single thread to keep time on registered
-actions and uses an ActionPool to execute
-actions. Simple and effective.
-
-install (easy):
-
-gem install ActionTimer
-
-install (less easy):
-
-git clone http://github.com/spox/actiontimer.git
-cd actiontimer
-gem build actiontimer.gemspec
-gem install ActionTimer-x.x.x.gem
-
-Simple example of using the timer:
-
-require 'actiontimer'
-
-timer = ActionTimer::Timer.new
-
-timer.add(10){puts "#{Time.now}: This is timed every 10 seconds"}
-timer.add(15){puts "#{Time.now}: This is timed every 15 seconds"}
-loop do
-    puts "#{Time.now}: Main loop that sleeps for 5 seconds"
-    sleep(5)
-end
-
-Output:
-
-2009-04-13 17:41:39 -0700: Main loop that sleeps for 5 seconds
-2009-04-13 17:41:44 -0700: Main loop that sleeps for 5 seconds
-2009-04-13 17:41:49 -0700: This is timed every 10 seconds
-2009-04-13 17:41:49 -0700: Main loop that sleeps for 5 seconds
-2009-04-13 17:41:54 -0700: This is timed every 15 seconds
-2009-04-13 17:41:54 -0700: Main loop that sleeps for 5 seconds
-2009-04-13 17:41:59 -0700: This is timed every 10 seconds
-2009-04-13 17:41:59 -0700: Main loop that sleeps for 5 seconds
-2009-04-13 17:42:04 -0700: Main loop that sleeps for 5 seconds
-2009-04-13 17:42:09 -0700: This is timed every 10 seconds
-2009-04-13 17:42:09 -0700: This is timed every 15 seconds
-2009-04-13 17:42:09 -0700: Main loop that sleeps for 5 seconds

data/README~

@@ -1,48 +0,0 @@
-            == ActionTimer ==
-  ~ Simple timing for a complex world ~
-
-ActionTimer is a helper for timed events. It
-allows for single and recurring actions to
-be executed in an efficient manner. It makes
-use of a single thread to keep time on registered
-actions and uses an ActionPool to execute
-actions. Simple and effective.
-
-install (easy):
-
-gem install ActionTimer
-
-install (less easy):
-
-git clone http://github.com/spox/actiontimer.git
-cd actiontimer
-gem build actiontimer.gemspec
-gem install ActionTimer-x.x.x.gem
-
-Simple example of using the timer:
-
-require 'actiontimer'
-
-timer = ActionTimer::Timer.new
-
-timer.add(10){puts "#{Time.now}: This is timed every 10 seconds"}
-timer.add(15){puts "#{Time.now}: This is timed every 15 seconds"}
-loop do
-    puts "#{Time.now}: Main loop that sleeps for 5 seconds"
-    sleep(5)
-end
-
-Output:
-
-2009-04-13 13:41:39 -0700: Main loop that sleeps for 5 seconds
-2009-04-13 13:41:44 -0700: Main loop that sleeps for 5 seconds
-2009-04-13 13:41:49 -0700: This is timed every 10 seconds
-2009-04-13 13:41:49 -0700: Main loop that sleeps for 5 seconds
-2009-04-13 13:41:54 -0700: This is timed every 15 seconds
-2009-04-13 13:41:54 -0700: Main loop that sleeps for 5 seconds
-2009-04-13 13:41:59 -0700: This is timed every 10 seconds
-2009-04-13 13:41:59 -0700: Main loop that sleeps for 5 seconds
-2009-04-13 13:42:04 -0700: Main loop that sleeps for 5 seconds
-2009-04-13 13:42:09 -0700: This is timed every 10 seconds
-2009-04-13 13:42:09 -0700: This is timed every 15 seconds
-2009-04-13 13:42:09 -0700: Main loop that sleeps for 5 seconds

data/lib/actiontimer/Action.rb~

@@ -1,69 +0,0 @@
-module ActionTimer
-    class Action
-    
-        attr_accessor :owner
-    
-        # timer:: Timer this action resides within
-        # period:: amount of time between runs
-        # once:: only run this action once
-        # data:: data to pass to block
-        # block:: block to be executed
-        def initialize(timer, period, once=false, data=nil, &block)
-            @period = period.to_f
-            @block = block
-            @data = data
-            @once = once
-            @due = false
-            @timer = timer
-            @completed = false
-            @wait_remaining = @period
-            @owner = nil
-        end
-        
-        # o:: Object that added this action
-        # Adds an owner for this action. Useful
-        # for clearing all actions for a given
-        # object from the timer
-        def owner=(o)
-            @owner = o
-        end
-        
-        # amount:: amount of time that has passed
-        # Decrement remaining wait time by given amount
-        def tick(amount)
-            @wait_remaining = @wait_remaining - amount if @wait_remaining > 0
-            @wait_remaining = 0 if @wait_remaining < 0
-            @completed = true if @once && @wait_remaining <= 0
-        end
-        
-        # Time remaning before Action is due
-        def remaining
-            @wait_remaining <= 0 ? 0 : @wait_remaining
-        end
-        
-        # new_time:: new period
-        # Resets the wait period between runs
-        def reset_period(new_time)
-            @period = new_time.to_f
-            @wait_remaining = @period
-            @timer.wakeup
-        end
-        
-        # Action is ready to be destroyed
-        def is_complete?
-            @completed
-        end
-        
-        # Used for scheduling with Timer. Resets the interval
-        # and returns itself
-        def schedule
-            @wait_remaining = @period
-            return self
-        end
-        
-        # Run the action
-        def run
-            @data.nil? ? @block.call : @block.call(@data)
-        end
-    end
-end

data/lib/actiontimer/Timer.rb~

@@ -1,140 +0,0 @@
-require 'actionpool'
-['Action', 'Exceptions', 'LogHelper'].each{|f| require "actiontimer/#{f}"}
-
-module ActionTimer
-    class Timer
-        # pool:: ActionPool for processing actions
-        # Creates a new timer
-        def initialize(pool=nil, logger=nil)
-            @actions = []
-            @new_actions = []
-            @timer_thread = nil
-            @stop_timer = false
-            @add_lock = Mutex.new
-            @awake_lock = Mutex.new
-            @new_actions = Queue.new
-            @pool = pool.nil? ? ActionPool::Pool.new : pool
-            @logger = LogHelper.new(logger)
-            start
-        end
-        
-        # Forcibly wakes the timer early
-        def wakeup
-            return unless @awake_lock.try_lock
-            @timer_thread.wakeup if @timer_thread.status == 'sleep'
-            @awake_lock.unlock
-        end
-        
-        # period:: amount of time between runs
-        # once:: only run this action once
-        # data:: data to pass to block
-        # owner:: owner of Action
-        # func:: block to be executed
-        # Add a new action to block
-        def add(period, once=false, data=nil, owner=nil, &func)
-            action = Action.new(self, period, once, data, &func)
-            action.owner = owner unless owner.nil?
-            @add_lock.synchronize{ @new_actions << action }
-            wakeup
-            return action
-        end
-        
-        # actions:: Array of actions
-        # Add multiple Actions to the timer at once
-        def mass_add(actions)
-            raise InvalidType.new(Array, actions.class) unless actions.is_a?(Array)
-            actions.each do |action|
-                raise InvalidType.new(ActionTimer::Action, action.class) unless action.is_a?(Action)
-            end
-            @add_lock.synchronize{ @new_actions = @new_actions + actions }
-            wakeup
-        end
-        
-        # action:: Action to remove from timer
-        # Remove given action from timer
-        def remove(action)
-            raise InvalidType.new(ActionTimer::Action, action.class) unless action.is_a?(Action)
-            @actions.delete(action)
-            wakeup
-        end
-        
-        # Start the timer
-        def start
-            raise AlreadyRunning.new unless @timer_thread.nil?
-            @timer_thread = Thread.new do
-                begin
-                    until @stop_timer do
-                        to_sleep = get_min_sleep
-                        if((to_sleep.nil? || to_sleep > 0) && @new_actions.empty?)
-                            @awake_lock.unlock if @awake_lock.locked?
-                            actual_sleep = to_sleep.nil? ? sleep : sleep(to_sleep)
-                            @awake_lock.lock
-                        else
-                            actual_sleep = 0
-                        end
-                        tick(actual_sleep)
-                        add_waiting_actions
-                    end
-                rescue Object => boom
-                    @logger.fatal("Timer encountered an unexpected error: #{boom}\n#{boom.backtrace.join("\n")}")
-                end
-            end
-        end
-        
-        # Stop the timer
-        def stop
-            @stop_timer = true
-            wakeup
-            @timer_thread.join
-        end
-        
-        # owner:: owner actions to remove
-        # Clears timer of actions. If an owner is supplied
-        # only actions owned by owner will be removed
-        def clear(owner=nil)
-            if(owner.nil?)
-                @actions.clear
-                @new_actions.clear
-            else
-                @actions.each{|a| @actions.delete(a) if a.owner == owner}
-            end
-            wakeup
-        end
-        
-        private
-        
-        def get_min_sleep
-            min = @actions.map{|a|a.remaining}.sort[0]
-            unless(min.nil? || min > 0)
-                @actions.each{|a|@actions.delete(a) if a.remaining == 0} # kill stuck actions
-                min = get_min_sleep
-            end
-            return min
-        end
-        
-        def add_waiting_actions
-            @add_lock.synchronize do
-                @actions = @actions + @new_actions
-                @new_actions.clear
-            end
-        end
-        
-        def tick(time_passed)
-            @actions.each do |action|
-                action.tick(time_passed)
-                if(action.due?)
-                    remove(action) if action.is_complete?
-                    action = action.schedule
-                    @pool.process do
-                        begin
-                            action.run
-                        rescue Object => boom
-                            @logger.error("Timer caught an error while running action: #{boom}\n#{boom.backtrace.join("\n")}")
-                        end
-                    end
-                end
-            end
-        end
-        
-    end
-end