daeltar-clockwork 0.2.4

data/README.md

@@ -0,0 +1,142 @@
+Clockwork - a clock process to replace cron
+===========================================
+
+Cron is non-ideal for running scheduled application tasks, especially in an app
+deployed to multiple machines.  [More details.](http://adam.heroku.com/past/2010/4/13/rethinking_cron/)
+
+Clockwork is a cron replacement.  It runs as a lightweight, long-running Ruby
+process which sits alongside your web processes (Mongrel/Thin) and your worker
+processes (DJ/Resque/Minion/Stalker) to schedule recurring work at particular
+times or dates.  For example, refreshing feeds on an hourly basis, or send
+reminder emails on a nightly basis, or generating invoices once a month on the
+1st.
+
+Quickstart
+----------
+
+Create clock.rb:
+
+    require 'clockwork'
+    include Clockwork
+
+    handler do |job|
+      puts "Running #{job}"
+    end
+
+    every(10.seconds, 'frequent.job')
+    every(3.minutes, 'less.frequent.job')
+    every(1.hour, 'hourly.job')
+
+    every(1.day, 'midnight.job', :at => '00:00')
+
+Run it with the clockwork binary:
+
+    $ clockwork clock.rb
+    Starting clock for 4 events: [ frequent.job less.frequent.job hourly.job midnight.job ]
+    Triggering frequent.job
+
+Use with queueing
+-----------------
+
+The clock process only makes sense as a place to schedule work to be done, not
+to do the work.  It avoids locking by running as a single process, but this
+makes it impossible to parallelize.  For doing the work, you should be using a
+job queueing system, such as
+[Delayed Job](http://www.therailsway.com/2009/7/22/do-it-later-with-delayed-job),
+[Beanstalk/Stalker](http://adam.heroku.com/past/2010/4/24/beanstalk_a_simple_and_fast_queueing_backend/),
+[RabbitMQ/Minion](http://adamblog.heroku.com/past/2009/9/28/background_jobs_with_rabbitmq_and_minion/), or
+[Resque](http://github.com/blog/542-introducing-resque).  This design allows a
+simple clock process with no locks, but also offers near infinite horizontal
+scalability.
+
+For example, if you're using Beanstalk/Staker:
+
+    require 'stalker'
+
+    handler { |job| Stalker.enqueue(job) }
+
+    every(1.hour, 'feeds.refresh')
+    every(1.day, 'reminders.send', :at => '01:30')
+
+Using a queueing system which doesn't require that your full application be
+loaded is preferable, because the clock process can keep a tiny memory
+footprint.  If you're using DJ or Resque, however, you can go ahead and load
+your full application enviroment, and use per-event blocks to call DJ or Resque
+enqueue methods.  For example, with DJ/Rails:
+
+    require 'config/boot'
+    require 'config/environment'
+
+    every(1.hour, 'feeds.refresh') { Feed.send_later(:refresh) }
+    every(1.day, 'reminders.send', :at => '01:30') { Reminder.send_later(:send_reminders) }
+
+Anatomy of a clock file
+-----------------------
+
+clock.rb is standard Ruby.  Since we include the Clockwork module (the
+clockwork binary does this automatically, or you can do it explicitly), this
+exposes a small DSL ("handler" and "every") to define the handler for events,
+and then the events themselves.
+
+The handler typically looks like this:
+
+    handler { |job| enqueue_your_job(job) }
+
+This block will be invoked every time an event is triggered, with the job name
+passed in.  In most cases, you should be able to pass the job name directly
+through to your queueing system.
+
+The second part of the file are the events, which roughly resembles a crontab:
+
+    every(5.minutes, 'thing.do')
+    every(1.hour, 'otherthing.do')
+
+In the first line of this example, an event will be triggered once every five
+minutes, passing the job name 'thing.do' into the handler.  The handler shown
+above would thus call enqueue_your_job('thing.do').
+
+You can also pass a custom block to the handler, for job queueing systems that
+rely on classes rather than job names (i.e. DJ and Resque).  In this case, you
+need not define a general event handler, and instead provide one with each
+event:
+
+    every(5.minutes, 'thing.do') { Thing.send_later(:do) }
+
+If you provide a custom handler for the block, the job name is used only for
+logging.
+
+You can also use blocks to do more complex checks:
+
+    every(1.day, 'check.leap.year') do
+      Stalker.enqueue('leap.year.party') if Time.now.year % 4 == 0
+    end
+
+In production
+-------------
+
+Only one clock process should ever be running across your whole application
+deployment.  For example, if your app is running on three VPS machines (two app
+servers and one database), your app machines might have the following process
+topography:
+
+* App server 1: 3 web (thin start), 3 workers (rake jobs:work), 1 clock (clockwork clock.rb)
+* App server 2: 3 web (thin start), 3 workers (rake jobs:work)
+
+You should use Monit, God, Upstart, or Inittab to keep your clock process
+running the same way you keep your web and workers running.
+
+Meta
+----
+
+Created by Adam Wiggins
+
+Inspired by [rufus-scheduler](http://rufus.rubyforge.org/rufus-scheduler/) and [http://github.com/bvandenbos/resque-scheduler](resque-scehduler)
+
+Design assistance from Peter van Hardenberg and Matthew Soldo
+
+Patches contributed by Mark McGranaghan
+
+Released under the MIT License: http://www.opensource.org/licenses/mit-license.php
+
+http://github.com/adamwiggins/clockwork
+

data/Rakefile

@@ -0,0 +1,23 @@
+require 'bundler/setup'
+require 'jeweler'
+
+Jeweler::Tasks.new do |s|
+  s.name = "daeltar-clockwork"
+  s.summary = "A scheduler process to replace cron."
+  s.description = "A scheduler process to replace cron, using a more flexible Ruby syntax running as a single long-running process.  Inspired by rufus-scheduler and resque-scheduler."
+  s.author = "Adam Wiggins"
+  s.email = "adam@heroku.com"
+  s.homepage = "http://github.com/adamwiggins/clockwork"
+  s.executables = [ "clockwork" ]
+  s.rubyforge_project = "daeltar-clockwork"
+
+  s.files = FileList["[A-Z]*", "{bin,lib}/**/*"]
+end
+
+Jeweler::GemcutterTasks.new
+
+task 'test' do
+  sh "ruby test/clockwork_test.rb"
+end
+
+task :build => :test

data/VERSION

@@ -0,0 +1 @@
+0.2.4

data/bin/clockwork

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+
+STDERR.sync = STDOUT.sync = true
+
+require File.expand_path('../../lib/clockwork', __FILE__)
+include Clockwork
+
+usage = "clockwork <clock.rb>"
+file = ARGV.shift or abort usage
+
+file = "./#{file}" unless file.match(/^[\/.]/)
+
+require file
+
+trap('INT') do
+  puts "\rExiting"
+  exit
+end
+
+run

data/lib/clockwork.rb

@@ -0,0 +1,123 @@
+module Clockwork
+  class FailedToParse < StandardError; end;
+
+  class ClockworkEvent
+    attr_accessor :job, :last
+
+    def initialize(period, job, block, options={})
+      @period = period
+      @job = job
+      @at = parse_at(options[:at])
+      @last = nil
+      @block = block
+    end
+
+    def to_s
+      @job
+    end
+
+    def time?(t)
+      ellapsed_ready = (@last.nil? or (t - @last).to_i >= @period)
+      time_ready = (@at.nil? or (t.hour == @at[0] and t.min == @at[1]))
+      ellapsed_ready and time_ready
+    end
+
+    def run(t)
+      @last = t
+      @block.call(@job)
+    rescue => e
+      log_error(e)
+    end
+
+    def log_error(e)
+      STDERR.puts exception_message(e)
+    end
+
+    def exception_message(e)
+      msg = [ "Exception #{e.class} -> #{e.message}" ]
+
+      base = File.expand_path(Dir.pwd) + '/'
+      e.backtrace.each do |t|
+        msg << "   #{File.expand_path(t).gsub(/#{base}/, '')}"
+      end
+
+      msg.join("\n")
+    end
+
+    def parse_at(at)
+      return unless at
+      m = at.match(/^(\d\d):(\d\d)$/)
+      raise FailedToParse, at unless m
+      hour, min = m[1].to_i, m[2].to_i
+      raise FailedToParse, at if hour >= 24 or min >= 60
+      [ hour, min ]
+    end
+  end
+
+  extend self
+
+  def handler(&block)
+    @@handler = block
+  end
+
+  class NoHandlerDefined < RuntimeError; end
+
+  def get_handler
+    raise NoHandlerDefined unless (defined?(@@handler) and @@handler)
+    @@handler
+  end
+
+  def every(period, job, options={}, &block)
+    event = ClockworkEvent.new(period, job, block || get_handler, options)
+    @@events ||= []
+    @@events << event
+    event
+  end
+
+  def run
+    log "Starting clock for #{@@events.size} events: [ " + @@events.map { |e| e.to_s }.join(' ') + " ]"
+    loop do
+      tick
+      sleep 1
+    end
+  end
+
+  def log(msg)
+    puts msg
+  end
+
+  def tick(t=Time.now)
+    to_run = @@events.select do |event|
+      event.time?(t)
+    end
+
+    to_run.each do |event|
+      log "Triggering #{event}"
+      event.run(t)
+    end
+
+    to_run
+  end
+
+  def clear!
+    @@events = []
+    @@handler = nil
+  end
+  
+end
+
+unless 1.respond_to?(:seconds) 
+  class Numeric
+    def seconds; self; end
+    alias :second :seconds
+
+    def minutes; self * 60; end
+    alias :minute :minutes
+
+    def hours; self * 3600; end
+    alias :hour :hours
+
+    def days; self * 86400; end
+    alias :day :days
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: daeltar-clockwork
+version: !ruby/object:Gem::Version 
+  hash: 31
+  prerelease: 
+  segments: 
+  - 0
+  - 2
+  - 4
+  version: 0.2.4
+platform: ruby
+authors: 
+- Adam Wiggins
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-30 00:00:00 Z
+dependencies: []
+
+description: A scheduler process to replace cron, using a more flexible Ruby syntax running as a single long-running process.  Inspired by rufus-scheduler and resque-scheduler.
+email: adam@heroku.com
+executables: 
+- clockwork
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- README.md
+- Rakefile
+- VERSION
+- bin/clockwork
+- lib/clockwork.rb
+homepage: http://github.com/adamwiggins/clockwork
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: daeltar-clockwork
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: A scheduler process to replace cron.
+test_files: []
+