clockwork 0.7.7 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7deeb150ded639846749af6efb04b31157dc430f
+  data.tar.gz: d97f85b001f54997b6c5fd5f2c160da31c8d0a73
+SHA512:
+  metadata.gz: b6d0b9c662b085d8243aaa23e00fc1c4549810ec3d346ce0b789eef518f7c839ea830d9c8ec7b785d33cdce81a3587e13b097673cd5ca3e133e40f8133007edb
+  data.tar.gz: b162bd32440586badc9156aa06738bda2ad581474d23bf7daf946d8c8a6aa7e55d6e63129ebd9776dc100bc02a2bfae02b21b06f31d3510968c0410f1c724f53

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2010-2014 Adam Wiggins, tomykaira <tomykaira@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -103,50 +103,70 @@ 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
+Use with database events
 -----------------------
 
-You can dynamically add tasks from a database to be scheduled along with the regular events in clock.rb.
+In addition to managing static events in your `clock.rb`, you can configure clockwork to synchronise with dynamic events from a database. Like static events, these database-backed events say when they should be run, and how frequently; the difference being that if you change those settings in the database, they will be reflected in clockwork.
 
-To do this, use the `sync_database_tasks` method call:
+To keep the database events in sync with clockwork, a special manager class `DatabaseEvents::Manager` is used. You tell it to sync a database-backed model using the `sync_database_events` method, and then, at the frequency you specify, it will fetch all the events from the database, and ensure clockwork is using the latest settings.
+
+### Example `clock.rb` file
+
+Here we're using an `ActiveRecord` model called `ClockworkDatabaseEvent` to store events in the database:
 
 ```ruby
 require 'clockwork'
-require 'clockwork/manager_with_database_tasks'
+require 'clockwork/manager_with_database_events'
 require_relative './config/boot'
 require_relative './config/environment'
- 
+
 module Clockwork
 
   # required to enable database syncing support
-  Clockwork.manager = ManagerWithDatabaseTasks.new
+  Clockwork.manager = DatabaseEvents::Manager.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
+  sync_database_events model: ClockworkDatabaseEvent, every: 1.minute do |model_instance|
 
-    # Or, e.g. if your queue system just needs job names
-    # Stalker.enqueue(instance_job_name)
+    # do some work e.g...
+
+    # running a DelayedJob task, where #some_action is a method
+    # you've defined on the model, which does the work you need
+    model_instance.delay.some_action
+
+    # performing some work with Sidekiq
+    YourSidekiqWorkerClass.perform_async
   end
 
-  [...other tasks if you have...]
+  [other events 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).
+This tells clockwork to fetch all `ClockworkDatabaseEvent` instances from the database, creating an internal clockwork event for each one, configured based on the instance's `frequency`, `at` and optionally `name` and `tz` methods. It also says to reload the events from the database every `1.minute`; we need pick up any changes in the database frequently (choose a sensible reload frequency by changing the `every:` option).
+
+When one of the events is ready to be run (based on it's `frequency`, `at` and possible `tz` methods), clockwork arranges for the block passed to `sync_database_events` to be run. The above example shows how you could use either DelayedJob or Sidekiq to simply kick off a worker job. This approach is good because the ideal is to use clockwork as a simple scheduler, and avoid making it carry out any long-running tasks.
 
-Rails ActiveRecord models are a perfect candidate for the model class, but you could use something else. The only requirements are:
+### Your Model Classes
+
+`ActiveRecord` models are a perfect candidate for the model class. Having said that, 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 otherwise 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:
+    - `id` returning a unique identifier (this is needed to track changes to event settings)
+
+    - `frequency` returning the how frequently (in seconds) the database event should be run
+
+    - `at` return nil or `''` if not using `:at`, or otherwise any acceptable clockwork `:at` string
+
+    - (optionally) `name` returning the name for the event (used to identify it in the Clcockwork output)
+
+    - (optionally) `tz` returning the timezone to use (default is the local timezone)
+
+#### Example Setup
+
+Here's an example of one way of setting up your ActiveRecord models:
 
 ```ruby
 # db/migrate/20140302220659_create_frequency_periods.rb
@@ -160,45 +180,30 @@ class CreateFrequencyPeriods < ActiveRecord::Migration
   end
 end
 
-# 20140302221102_create_my_scheduled_tasks.rb
-class CreateMyScheduledTasks < ActiveRecord::Migration
+# 20140302221102_create_clockwork_database_events.rb
+class CreateClockworkDatabaseEvents < ActiveRecord::Migration
   def change
-    create_table :my_scheduled_tasks do |t|
+    create_table :clockwork_database_events do |t|
       t.integer :frequency_quantity
       t.references :frequency_period
       t.string :at
 
       t.timestamps
     end
-    add_index :my_scheduled_tasks, :frequency_period_id
+    add_index :clockwork_database_events, :frequency_period_id
   end
 end
 
-# app/models/my_scheduled_task.rb
-class MyScheduledTask < ActiveRecord::Base
-  include Sidekiq::Worker
-
+# app/models/clockwork_database_event.rb
+class ClockworkDatabaseEvent < ActiveRecord::Base
   belongs_to :frequency_period
-  attr_accessible :frequency_quantity, :frequency_period_id, :at 
+  attr_accessible :frequency_quantity, :frequency_period_id, :at
 
-  # Used by clockwork to schedule how frequently this task should be run
+  # Used by clockwork to schedule how frequently this event 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
@@ -215,8 +220,6 @@ 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
 ----------
 
@@ -297,7 +300,11 @@ Clockwork.every(1.second, 'myjob', :if => lambda { |_| true })
 
 ### :thread
 
-An event with `:thread => true`  runs in a different thread.
+In default, clockwork runs in single-process, single-thread.
+If an event handler takes long time, the main routine of clockwork is blocked until it ends.
+Clockwork does not misbehave, but the next event is blocked, and runs when the process is returned to the clockwork routine.
+
+This `:thread` option is to avoid blocking. An event with `:thread => true`  runs in a different thread.
 
 ```ruby
 Clockwork.every(1.day, 'run.me.in.new.thread', :thread => true)
@@ -441,12 +448,12 @@ 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|
+sync_database_events model: MyEvent, 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).
+You can use multiple `sync_database_events` 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/Rakefile

@@ -2,7 +2,7 @@ require 'bundler/gem_tasks'
 require 'rake/testtask'
 
 Rake::TestTask.new do |t|
-  t.test_files = FileList['test/*_test.rb']
+  t.test_files = FileList['test/**/*_test.rb']
   t.verbose = false
 end
 

data/clockwork.gemspec

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

data/clockworkd.1

@@ -0,0 +1,62 @@
+.TH CLOCKWORKD 1 "August 2014" "Ruby Gem" "clockwork"
+
+.SH NAME
+clockworkd - daemon executing clockwork scripts
+
+.SH SYNOPSIS
+\fBclockworkd\fR [-c \fIFILE\fR] [\fIOPTIONS\fR] {start|stop|restart|run}
+
+.SH DESCRIPTION
+\fBclockworkd\fR executes clockwork script as a daemon.
+
+You will need the \fBdaemons\fR gem to use \fBclockworkd\fR. It is not automatically installed, please install by yourself.
+
+.SH OPTIONS
+.TP
+\fB--pid-dir\fR=\fIDIR\fR
+Alternate directory in which to store the process ids. Default is \fIGEM_LOCATION\fR/tmp.
+
+.TP
+\fB-i\fR, \fB--identifier\fR=\fISTR\fR
+An identifier for the process. Default is clock file name.
+
+.TP
+\fB-l\fR, \fB--log\fR
+Redirect both STDOUT and STDERR to a logfile named clockworkd[.\fIidentifier\fR].output in the pid-file directory.
+
+.TP
+\fB--log-dir\fR=\fIDIR\fR
+A specific directory to put the log files into. Default location is pid directory.
+
+.TP
+\fB-m\fR, \fB--monitor\fR
+Start monitor process.
+
+.TP
+\fB-c\fR, \fB--clock\fR=\fIFILE\fR
+Clock .rb file. Default is \fIGEM_LOCATION\fR/clock.rb.
+
+.TP
+\fB-d\fR, \fB--dir\fR=\fIDIR\fR
+Directory to change to once the process starts
+
+.TP
+\fB-h\fR, \fB--help\fR
+Show help message.
+
+.SH BUGS
+If you find a bug, please create an issue \fIhttps://github.com/tomykaira/clockwork/issues\fR.
+
+For a bug fix or a feature request, please send a pull-request. Do not forget to add tests to show how your feature works, or what bug is fixed. All existing tests and new tests must pass (TravisCI is watching).
+
+.SH AUTHORS
+Created by Adam Wiggins.
+
+Inspired by rufus-scheduler and resque-scheduler.
+
+Design assistance from Peter van Hardenberg and Matthew Soldo.
+
+Patches contributed by Mark McGranaghan and Lukáš Konarovský.
+
+.SH SEE ALSO
+\fIhttps://github.com/tomykaira/clockwork\fR.

data/lib/clockwork/at.rb

@@ -33,7 +33,7 @@ module Clockwork
       raise FailedToParse, at
     end
 
-    attr_writer :min, :hour, :wday
+    attr_accessor :min, :hour, :wday
 
     def initialize(min, hour=NOT_SPECIFIED, wday=NOT_SPECIFIED)
       @min = min
@@ -48,6 +48,10 @@ module Clockwork
         (@wday == NOT_SPECIFIED or t.wday == @wday)
     end
 
+    def == other
+      @min == other.min && @hour == other.hour && @wday == other.wday
+    end
+
     private
     def valid?
       @min == NOT_SPECIFIED || (0..59).cover?(@min) &&

data/lib/clockwork/database_events.rb

@@ -0,0 +1,26 @@
+require_relative 'database_events/event'
+require_relative 'database_events/sync_performer'
+require_relative 'database_events/registry'
+require_relative 'database_events/manager'
+
+# TERMINOLOGY
+#
+# For clarity, we have chosen to define terms as follows for better communication in the code, and when 
+# discussing the database event implementation.
+#
+# "Event":      "Native" Clockwork events, whether Clockwork::Event or Clockwork::DatabaseEvents::Event
+# "Model":      Database-backed model instances representing events to be created in Clockwork
+
+module Clockwork
+
+  module Methods
+    def sync_database_events(options={}, &block)
+      DatabaseEvents::SyncPerformer.setup(options, &block)
+    end
+  end
+
+  extend Methods
+
+  module DatabaseEvents
+  end
+end

data/lib/clockwork/database_events/event.rb

@@ -0,0 +1,38 @@
+module Clockwork
+
+  module DatabaseEvents
+
+    class Event < Clockwork::Event
+
+      attr_accessor :sync_performer, :at
+
+      def initialize(manager, period, job, block, sync_performer, options={})
+        super(manager, period, job, block, options)
+        @sync_performer = sync_performer
+        @sync_performer.register(self, job)
+      end
+
+      def name
+        (job.respond_to?(:name) && job.name) ? job.name : "#{job.class}:#{job.id}"
+      end
+
+      def to_s
+        name
+      end
+
+      def name_or_frequency_has_changed?(model)
+        name_has_changed?(model) || frequency_has_changed?(model)
+      end
+
+      private
+      def name_has_changed?(model)
+        !job.respond_to?(:name) || job.name != model.name
+      end
+
+      def frequency_has_changed?(model)
+        @period != model.frequency
+      end
+    end
+
+  end
+end

data/lib/clockwork/database_events/manager.rb

@@ -0,0 +1,20 @@
+module Clockwork
+
+  module DatabaseEvents
+
+    class Manager < Clockwork::Manager
+
+      def unregister(event)
+        @events.delete(event)
+      end
+
+      def register(period, job, block, options)
+        @events << if options[:from_database]
+          Clockwork::DatabaseEvents::Event.new(self, period, job, (block || handler), options.fetch(:sync_performer), options)
+        else
+          Clockwork::Event.new(self, period, job, block || handler, options)
+        end
+      end
+    end
+  end
+end

data/lib/clockwork/database_events/registry.rb

@@ -0,0 +1,39 @@
+module Clockwork
+
+  module DatabaseEvents
+
+    class Registry
+
+      def initialize
+        @events = Hash.new []
+      end
+
+      def register(event, model)
+        @events[model.id] = @events[model.id] + [event]
+      end
+
+      def unregister(model)
+        unregister_by_id(model.id)
+      end
+
+      def unregister_by_id(id)
+        @events[id].each{|e| Clockwork.manager.unregister(e) }
+        @events.delete(id)
+      end
+
+      def unregister_all_except(ids)
+        (@events.keys - ids).each{|id| unregister_by_id(id) }
+      end
+
+      # all events of same id will have same frequency/name, just different ats
+      def event_for(model)
+        events_for(model).first
+      end
+
+      def events_for(model)
+        @events[model.id]
+      end
+    end
+
+  end
+end

data/lib/clockwork/database_events/sync_performer.rb

@@ -0,0 +1,94 @@
+require_relative '../database_events'
+
+module Clockwork
+
+  module DatabaseEvents
+
+    class SyncPerformer
+
+      PERFORMERS = []
+
+      def self.setup(options={}, &block)
+        model_class = options.fetch(:model) { raise KeyError, ":model must be set to the model class" }
+        every = options.fetch(:every) { raise KeyError, ":every must be set to the database sync frequency" }
+
+        sync_performer = self.new(model_class, &block)
+
+        # create event that syncs clockwork events with events coming from database-backed model
+        Clockwork.manager.every every, "sync_database_events_for_model_#{model_class}" do
+          sync_performer.sync
+        end
+      end
+
+      def initialize(model_class, &proc)
+        @model_class = model_class
+        @block = proc
+        @database_event_registry = Registry.new
+
+        PERFORMERS << self
+      end
+
+      # delegates to Registry
+      def register(event, model)
+        @database_event_registry.register(event, model)
+      end
+
+      # Ensure clockwork events reflect events from database-backed model
+      # Adds any new events, modifies updated ones, and delets removed ones
+      def sync
+        model_ids_that_exist = []
+
+        @model_class.all.each do |model|
+          model_ids_that_exist << model.id
+          if are_different?(@database_event_registry.event_for(model), model)
+            create_or_recreate_event(model)
+          end
+        end
+        @database_event_registry.unregister_all_except(model_ids_that_exist)
+      end
+
+      private
+      def are_different?(event, model)
+        return true if event.nil?
+        event.name_or_frequency_has_changed?(model) || ats_have_changed?(model)
+      end
+
+      def ats_have_changed?(model)
+        model_ats = ats_array_for_event(model)
+        event_ats = ats_array_from_model(model)
+
+        model_ats != event_ats
+      end
+
+      def ats_array_for_event(model)
+        @database_event_registry.events_for(model).collect{|event| event.at }.compact
+      end
+
+      def ats_array_from_model(model)
+        (at_strings_for(model) || []).collect{|at| At.parse(at) }
+      end
+
+      def at_strings_for(model)
+        model.at.to_s.empty? ? nil : model.at.split(',').map(&:strip)
+      end
+
+      def create_or_recreate_event(model)
+        if @database_event_registry.event_for(model)
+          @database_event_registry.unregister(model)
+        end
+
+        options = {
+          :from_database => true,
+          :sync_performer => self,
+          :at => at_strings_for(model)
+        }
+
+        options[:tz] = model.tz if model.respond_to?(:tz)
+
+        # we pass actual model instance as the job, rather than just name
+        Clockwork.manager.every model.frequency, model, options, &@block
+      end
+    end
+
+  end
+end