clockwork 0.7.2 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b89afd90ad2ece3d2dab28742a2f463deb786754
-  data.tar.gz: cd50508469046e76e210aeb219e66aa553a0febd
+  metadata.gz: fae14bd8566db2cb7c3be8c5c9625b01dc66ae00
+  data.tar.gz: ecbed0c0a9cf6017a0e62f62da9cfb67112624da
 SHA512:
-  metadata.gz: 4dc13ede6fad5c5bd63a9755ec0b6816da426321d4de3ef3a20db5271b22db00eb437aaf93057026bd189f608906fd08701dad9241e4e2da971fde79f1657894
-  data.tar.gz: a264b85a81b8f4363f38f811a0077bb9fb255497dca480324ab3f2decf17e290c0092e99a4c19d23728663668c32185353bab050add94797c34964ab61cee499
+  metadata.gz: c75686b464777f74d87ca6b15d3ac1d57ee83f190e22d32c6b585fecb86c5192575f90d6151588e9454f7d3f8054bd1c63f3fa4d6a3a067f1d93bbd10a14fe4a
+  data.tar.gz: c68c69e967a99422394197ed570c2c0ce0968e73a7495ec44a55158b99a6c6450a84fd3160d4707d95c5385ddc00b584f4fb350a6b0566b44222f8201215c504

data/README.md

@@ -103,6 +103,120 @@ every(1.hour, 'feeds.refresh') { Feed.send_later(:refresh) }
 every(1.day, 'reminders.send', :at => '01:30') { Reminder.send_later(:send_reminders) }
 ```
 
+Use with database tasks
+-----------------------
+
+You can dynamically add tasks from a database to be scheduled along with the regular events in clock.rb.
+
+To do this, use the `sync_database_tasks` method call:
+
+```ruby
+require 'clockwork'
+require 'clockwork/manager_with_database_tasks'
+require_relative './config/boot'
+require_relative './config/environment'
+ 
+module Clockwork
+
+  # required to enable database syncing support
+  Clockwork.manager = ManagerWithDatabaseTasks.new
+
+  sync_database_tasks model: MyScheduledTask, every: 1.minute do |instance_job_name|
+    # Where your model will acts as a worker:
+    id = instance_job_name.split(':').last
+    task = MyScheduledTask.find(id)
+    task.perform_async
+
+    # Or, e.g. if your queue system just needs job names
+    # Stalker.enqueue(instance_job_name)
+  end
+
+  [...other tasks if you have...]
+
+end
+```
+
+This tells clockwork to fetch all MyScheduledTask instances from the database, and create an event for each, configured based on the instances' `frequency`, `name`, and `at` methods. It also says to reload the tasks from the database every 1.minute - we need to frequently do this as they could have changed (but you can choose a sensible reload frequency by changing the `every:` option). Note that the database sync event will always run on the minute-boundary (i.e. HH:MM::00), and that events which have been synced from the database won't be run in that same clock cycle (this prevents a task from the database being run twice).
+
+Rails ActiveRecord models are a perfect candidate for the model class, but you could use something else. The only requirements are:
+
+  1. the class responds to `all` returning an array of instances from the database
+  2. the instances returned respond to:
+      `frequency` returning the how frequently (in seconds) the database task should be run
+      `name` returning the task's job name (this is what gets passed into the block above)
+      `at` return nil or '' if not using :at, or any acceptable clockwork :at string
+
+Here's an example of one way of setting up your ActiveRecord models, using Sidekiq for background tasks, and making the model class a worker:
+
+```ruby
+# db/migrate/20140302220659_create_frequency_periods.rb
+class CreateFrequencyPeriods < ActiveRecord::Migration
+  def change
+    create_table :frequency_periods do |t|
+      t.string :name
+
+      t.timestamps
+    end
+  end
+end
+
+# 20140302221102_create_my_scheduled_tasks.rb
+class CreateMyScheduledTasks < ActiveRecord::Migration
+  def change
+    create_table :my_scheduled_tasks do |t|
+      t.integer :frequency_quantity
+      t.references :frequency_period
+      t.string :at
+
+      t.timestamps
+    end
+    add_index :my_scheduled_tasks, :frequency_period_id
+  end
+end
+
+# app/models/my_scheduled_task.rb
+class MyScheduledTask < ActiveRecord::Base
+  include Sidekiq::Worker
+
+  belongs_to :frequency_period
+  attr_accessible :frequency_quantity, :frequency_period_id, :at 
+
+  # Used by clockwork to schedule how frequently this task should be run
+  # Should be the intended number of seconds between executions
+  def frequency
+    frequency_quantity.send(frequency_period.name.pluralize)
+  end
+
+  # Used by clockwork to name this task internally for its logging
+  # Should return a reference for this task to be used in clockwork
+  # Include the instance ID if you want to be able to retrieve the 
+  # model instance inside the sync_database_tasks block in clock.rb
+  def name
+    "Database_MyScheduledTask:#{id}"
+  end
+
+  # Method required by Sidekiq
+  def perform
+    # the task that will be performed in the background
+  end
+end
+
+# app/models/frequency_period.rb
+class FrequencyPeriod < ActiveRecord::Base
+  attr_accessible :name
+end
+
+# db/seeds.rb
+...
+# creating the FrequencyPeriods
+[:second, :minute, :hour, :day, :week, :month].each do |period|
+  FrequencyPeriod.create(name: period)
+end
+...
+```
+
+You could, of course, create a separate Sidekiq or DelayedJob worker class under app/workers, and simply use the model referenced by clockwork to trigger that worker to run asynchronously.
+
 Event Parameters
 ----------
 
@@ -324,6 +438,16 @@ on(:after_tick) do
 end
 ```
 
+Finally, you can use tasks synchronised from a database as described in detail above:
+
+```ruby
+sync_database_tasks model: MyScheduledTask, every: 1.minute do |instance_job_name|
+  # what to do with each instance
+end
+```
+
+You can use multiple `sync_database_tasks` if you wish, so long as you use different model classes for each (ActiveRecord Single Table Inheritance could be a good idea if you're doing this).
+
 In production
 -------------
 

data/clockwork.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "clockwork"
-  s.version = "0.7.2"
+  s.version = "0.7.3"
 
   s.authors = ["Adam Wiggins", "tomykaira"]
   s.license = 'MIT'

data/lib/clockwork/manager_with_database_tasks.rb

@@ -0,0 +1,87 @@
+module Clockwork
+
+  module Methods
+    def sync_database_tasks(options={}, &block)
+      Clockwork.manager.sync_database_tasks(options, &block)
+    end
+  end
+
+  extend Methods
+
+  class ManagerWithDatabaseTasks < Manager
+
+    SECOND_TO_RUN_DATABASE_SYNC_AT = 0
+
+    def initialize
+      super
+      @events_from_database = []
+      @next_sync_database_tasks_identifier = 0
+    end
+
+    def sync_database_tasks(options={}, &block)
+      [:model, :every].each do |option|
+        raise ArgumentError.new("requires :#{option} option") unless options.include?(option)
+      end
+      raise ArgumentError.new(":every must be greater or equal to 1.minute") if options[:every] < 1.minute
+
+      model = options[:model]
+      frequency = options[:every]
+      sync_task_id = get_sync_task_id
+
+      # Prevent database tasks from running in same cycle as the database sync,
+      # as this can lead to the same task being run twice
+      options_to_run_database_sync_in_own_cycle  = { :if => lambda { |t| t.sec == SECOND_TO_RUN_DATABASE_SYNC_AT } }
+
+      # create event that syncs clockwork events with database events
+      every frequency, "sync_database_tasks_for_model_#{model}", options_to_run_database_sync_in_own_cycle do
+        reload_events_from_database sync_task_id, model, &block
+      end
+    end
+
+
+    protected
+
+    # sync_task_id's are used to group the database events from a particular sync_database_tasks call
+    # This method hands out the ids, incrementing the id to keep them unique.
+    def get_sync_task_id
+      current_sync_task_id = @next_sync_database_tasks_identifier
+      @next_sync_database_tasks_identifier += 1
+      current_sync_task_id
+    end
+
+    def reload_events_from_database(sync_task_id, model, &block)
+      @events_from_database[sync_task_id] = []
+
+      model.all.each do |db_task|
+        options = { from_database: true, :sync_task_id => sync_task_id }
+        options[:at] = db_task.at.split(',') unless db_task.at.blank?
+
+        # If database tasks can be scheduled in same clock cycle that database syncs occur
+        # then previous copy of database sync task will be stored and set to run (in #tick events variable)
+        # *before* we then delete all database tasks. This causes the task to be run at HH:00 (previous copy)
+        # and at HH:01 (newly fetched copy).
+        option_to_prevent_database_tasks_running_in_same_cycle_as_sync = { :if => lambda{|t| t.sec != SECOND_TO_RUN_DATABASE_SYNC_AT } }
+        every db_task.frequency,
+        db_task.name,
+        options.merge(option_to_prevent_database_tasks_running_in_same_cycle_as_sync),
+        &block
+      end
+    end
+
+    private
+
+    def events_to_run(t)
+      (@events + @events_from_database.flatten).select{|event| event.run_now?(t) }
+    end
+
+    def register(period, job, block, options)
+      event = Event.new(self, period, job, block || handler, options)
+      if options[:from_database]
+        @events_from_database[options[:sync_task_id]] << event
+      else
+        @events << event
+      end
+      event
+    end
+  end
+end

data/test/manager_with_database_tasks_test.rb

@@ -0,0 +1,190 @@
+require File.expand_path('../../lib/clockwork', __FILE__)
+require 'clockwork/manager_with_database_tasks'
+require 'rubygems'
+require 'contest'
+require 'mocha/setup'
+require 'time'
+require 'active_support/time'
+
+class ManagerWithDatabaseTasksTest < Test::Unit::TestCase
+
+  class ScheduledTask; end
+  class ScheduledTaskType2; end
+
+  setup do
+    @manager = Clockwork::ManagerWithDatabaseTasks.new
+    class << @manager
+      def log(msg); end
+    end
+    @manager.handler { }
+  end
+
+  def tick_at(now = Time.now, options = {})
+    seconds_to_tick_for = options[:and_every_second_for] || 0
+    number_of_ticks = seconds_to_tick_for + 1 # add one for right now
+    number_of_ticks.times{|i| @manager.tick(now + i) }
+  end
+
+  def next_minute(now = Time.now)
+    Time.new(now.year, now.month, now.day, now.hour, now.min + 1, 0)
+  end
+
+  describe "sync_database_tasks" do
+
+    describe "arguments" do
+
+      def test_does_not_raise_error_with_valid_arguments
+        @manager.sync_database_tasks(model: ScheduledTask, every: 1.minute) {}
+      end
+
+      def test_raises_argument_error_if_param_called_model_is_not_set
+        assert_raises ArgumentError do
+          @manager.sync_database_tasks(model: ScheduledTask) {}
+        end
+      end
+
+      def test_raises_argument_error_if_param_called_every_is_not_set
+        assert_raises ArgumentError do
+          @manager.sync_database_tasks(every: 1.minute) {}
+        end
+      end
+
+      def test_raises_argument_error_if_param_called_every_is_less_than_1_minute
+        assert_raises ArgumentError do
+          @manager.sync_database_tasks(model: ScheduledTask, every: 59.seconds) {}
+        end
+      end
+    end
+
+    setup do
+      @tasks_run = []
+      @scheduled_task1 = stub(:frequency => 10, :name => 'ScheduledTask:1', :at => nil)
+      @scheduled_task2 = stub(:frequency => 10, :name => 'ScheduledTask:2', :at => nil)
+      @scheduled_task1_modified = stub(:frequency => 5, :name => 'ScheduledTaskModified:1', :at => nil)
+      ScheduledTask.stubs(:all).returns([@scheduled_task1])
+
+      @database_reload_frequency = 1.minute
+
+      @now = Time.now
+      @next_minute = next_minute(@now) # database sync task only happens on minute boundary
+
+      # setup the database sync
+      @manager.sync_database_tasks model: ScheduledTask, every: @database_reload_frequency do |job_name|
+        @tasks_run << job_name
+      end
+    end
+
+    def test_does_not_fetch_database_tasks_until_next_minute
+      seconds_upto_and_including_next_minute = (@next_minute - @now).seconds.to_i + 1
+      tick_at(@now, :and_every_second_for => seconds_upto_and_including_next_minute)
+      assert_equal [], @tasks_run
+    end
+
+    def test_fetches_and_registers_database_task
+      tick_at(@next_minute, :and_every_second_for => 1.second)
+      assert_equal ["ScheduledTask:1"], @tasks_run
+    end
+
+    def test_multiple_database_tasks_can_be_registered
+      ScheduledTask.stubs(:all).returns([@scheduled_task1, @scheduled_task2])
+      tick_at(@next_minute, :and_every_second_for => 1.second)
+      assert_equal ["ScheduledTask:1", "ScheduledTask:2"], @tasks_run
+    end
+
+    def test_database_task_does_not_run_again_before_frequency_specified_in_database
+      tick_at(@next_minute, :and_every_second_for => 9.seconds) # runs at 1
+      assert_equal 1, @tasks_run.length
+    end
+
+    def test_database_task_runs_repeatedly_with_frequency_specified_in_database
+      tick_at(@next_minute, :and_every_second_for => 21.seconds) # runs at 1, 11, and 21
+      assert_equal 3, @tasks_run.length
+    end
+
+    def test_reloads_tasks_from_database
+      ScheduledTask.stubs(:all).returns([@scheduled_task1], [@scheduled_task2])
+      tick_at(@next_minute, :and_every_second_for => @database_reload_frequency.seconds)
+      @manager.tick # @scheduled_task2 should run immediately on next tick (then every 10 seconds)
+
+      assert_equal "ScheduledTask:2", @tasks_run.last
+    end
+
+    def test_reloaded_tasks_run_repeatedly
+      ScheduledTask.stubs(:all).returns([@scheduled_task1], [@scheduled_task2])
+      tick_at(@next_minute, :and_every_second_for => @database_reload_frequency.seconds + 11.seconds)
+      assert_equal ["ScheduledTask:2", "ScheduledTask:2"], @tasks_run[-2..-1]
+    end
+
+    def test_stops_running_deleted_database_task
+      ScheduledTask.stubs(:all).returns([@scheduled_task1], [])
+      tick_at(@next_minute, :and_every_second_for => @database_reload_frequency.seconds)
+      before = @tasks_run.dup
+
+      # tick through reload, and run for enough ticks that previous task would have run
+      tick_at(@next_minute + @database_reload_frequency.seconds + 20.seconds)
+      after = @tasks_run
+
+      assert_equal before, after
+    end
+
+    def test_reloading_task_with_modified_frequency_will_run_with_new_frequency
+      ScheduledTask.stubs(:all).returns([@scheduled_task1], [@scheduled_task1_modified])
+
+      tick_at(@next_minute, :and_every_second_for => 66.seconds)
+
+      # task1 runs at: 1, 11, 21, 31, 41, 51 (6 runs)
+      # database tasks are reloaded at: 60
+      # task1_modified runs at: 61 (next tick after reload) and then 66 (2 runs)
+      assert_equal 8, @tasks_run.length
+    end
+
+    # Catch a bug caused by allowing database tasks to be run in the same clock cycle that the database
+    # sync occurs. When this happens, a previously scheduled database task will be scheduled to run,
+    # we then fetch the same task afresh (wiping out the @events_from_database object), but the
+    # previously scheduled task still runs because #task `events` variable already stored it *before*
+    # we wiped out the @events_from_database objects.
+    #
+    # We have a situation like this:
+    #
+    # 12:31:00    #tick loops through events to run
+    #               sync_database_tasks_for_model_ task is run
+    #                 fetches database task 1 with :at => 12:32, and schedules it to run (object task 1')
+    #
+    # ...
+    #
+    # 12:32:00    #tick loops through events that should be run, of which task 1' is included
+    #               sync_database_tasks_for_model_ task is run
+    #                 fetches database task 1 with :at => 12:32, and schedules it to run (object task 1'')
+    #               task 1' is run
+    #
+    # 12:32:01    #tick loops through events that should be run, of which task 1'' is included
+    #               task 1'' is run
+    def test_daily_task_with_at_should_not_run_twice_when_already_scheduled
+      minute_after_next = next_minute(@next_minute)
+      at = minute_after_next.strftime('%H:%M')
+      @scheduled_task_with_at = stub(:frequency => 1.day, :name => 'ScheduledTaskWithAt:1', :at => at)
+      ScheduledTask.stubs(:all).returns([@scheduled_task_with_at])
+
+      # tick from now, though specified :at time
+      tick_at(@now, :and_every_second_for => (2 * @database_reload_frequency.seconds) + 1.second)
+
+      assert_equal 1, @tasks_run.length
+    end
+
+    def test_having_multiple_sync_database_tasks_will_work
+      ScheduledTask.stubs(:all).returns([@scheduled_task1])
+
+      # setup 2nd database sync
+      @scheduled_task_type2 = stub(:frequency => 10, :name => 'ScheduledTaskType2:1', :at => nil)
+
+      ScheduledTaskType2.stubs(:all).returns([@scheduled_task_type2])
+      @manager.sync_database_tasks model: ScheduledTaskType2, every: @database_reload_frequency do |job_name|
+        @tasks_run << job_name
+      end
+
+      tick_at(@next_minute, :and_every_second_for => 1.second)
+
+      assert_equal ["ScheduledTask:1", "ScheduledTaskType2:1"], @tasks_run
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clockwork
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.7.3
 platform: ruby
 authors:
 - Adam Wiggins
@@ -9,104 +9,104 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-14 00:00:00.000000000 Z
+date: 2014-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tzinfo
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: daemons
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: contest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: A scheduler process to replace cron, using a more flexible Ruby syntax
@@ -121,8 +121,8 @@ extensions: []
 extra_rdoc_files:
 - README.md
 files:
-- ".gitignore"
-- ".travis.yml"
+- .gitignore
+- .travis.yml
 - Gemfile
 - README.md
 - Rakefile
@@ -136,10 +136,12 @@ files:
 - lib/clockwork/at.rb
 - lib/clockwork/event.rb
 - lib/clockwork/manager.rb
+- lib/clockwork/manager_with_database_tasks.rb
 - test/at_test.rb
 - test/clockwork_test.rb
 - test/event_test.rb
 - test/manager_test.rb
+- test/manager_with_database_tasks_test.rb
 homepage: http://github.com/tomykaira/clockwork
 licenses:
 - MIT
@@ -150,17 +152,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.0
+rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
 summary: A scheduler process to replace cron.
@@ -169,3 +171,4 @@ test_files:
 - test/clockwork_test.rb
 - test/event_test.rb
 - test/manager_test.rb
+- test/manager_with_database_tasks_test.rb