clockwork 0.1.0

data/README.md

@@ -0,0 +1,98 @@
+Clockwork - a scheduler 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 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.
+
+Example
+-------
+
+Create schedule.rb:
+
+    require 'clockwork'
+    include Clockwork
+
+    every('10s') { puts 'every 10 seconds' }
+    every( '3m') { puts 'every 3 minutes' }
+    every( '1h') { puts 'once an hour' }
+
+    every('1d', :at => '00:00') { puts 'every night at midnight' }
+
+Run it with the clockwork binary:
+
+    $ clockwork schedule.rb
+
+Or run directly with Ruby:
+
+    $ ruby -r schedule -e Clockwork.run
+
+Use with queueing
+-----------------
+
+Clockwork 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 scheduler process with no locks, but also offers near infinite
+horizontal scalability.
+
+For example, if you're using Beanstalk/Staker:
+
+    require 'clockwork'
+    include Clockwork
+
+    require 'stalker'
+    include Stalker
+
+    every('1h') { enqueue('feeds.refresh') }
+    every('1d', :at => '01:30') { enqueue('reminders.send') }
+
+Using a queueing system which doesn't require that your full application be
+loaded is preferable, because the scheduler 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.  For example, with DJ/Rails:
+
+    require 'config/boot'
+    require 'config/environment'
+
+    require 'clockwork'
+    include Clockwork
+
+    every('1h') { Feed.send_later(:refresh) }
+    every('1d', :at => '01:30') { Reminder.send_later(:send_reminders) }
+
+In production
+-------------
+
+Only one scheduler 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:
+
+* Machine 1: 3 web (thin start), 3 workers (rake jobs:work), 1 scheduler (clockwork schedule.rb)
+* Machine 2: 3 web (thin start), 3 workers (rake jobs:work)
+
+You should use Monit, God, Upstart, or Inittab to keep your scheduler 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)
+
+Released under the MIT License: http://www.opensource.org/licenses/mit-license.php
+
+http://github.com/adamwiggins/clockwork
+

data/Rakefile

@@ -0,0 +1,16 @@
+require 'jeweler'
+
+Jeweler::Tasks.new do |s|
+	s.name = "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 = "clockwork"
+
+	s.files = FileList["[A-Z]*", "{bin,lib}/**/*"]
+end
+
+Jeweler::GemcutterTasks.new

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/bin/clockwork

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'clockwork'
+include Clockwork
+
+usage = "clockwork <schedule.rb>"
+file = ARGV.shift or abort usage
+
+require file
+
+trap('INT') do
+	puts "\rExiting"
+	exit
+end
+
+run

data/lib/clockwork.rb

@@ -0,0 +1,80 @@
+module Clockwork
+	class Event
+		def initialize(span, options={}, &block)
+			@secs = parse_span(span)
+			@at = parse_at(options[:at])
+			@last = nil
+			@block = block
+		end
+
+		def time?(t)
+			ellapsed_ready = (@last.nil? or (t - @last).to_i >= @secs)
+			time_ready = (@at.nil? or (t.hour == @at[0] and t.min == @at[1]))
+			ellapsed_ready and time_ready
+		end
+
+		def run(t)
+			@block.call
+			@last = t
+		end
+
+		class FailedToParse < RuntimeError; end
+
+		def parse_span(span)
+			m = span.match(/^(\d+)([smhd])$/)
+			raise FailedToParse, span unless m
+			ordinal, magnitude = m[1].to_i, m[2]
+			ordinal * magnitude_multiplier[magnitude]
+		end
+
+		def magnitude_multiplier
+			{
+				's' => 1,
+				'm' => 60,
+				'h' => 60*60,
+				'd' => 24*60*60
+			}
+		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 every(span, options={}, &block)
+		event = Event.new(span, options, &block)
+		@@events ||= []
+		@@events << event
+		event
+	end
+
+	def run
+		loop do
+			tick
+			sleep 1
+		end
+	end
+
+	def tick(t=Time.now)
+		to_run = @@events.select do |event|
+			event.time?(t)
+		end
+
+		to_run.each do |event|
+			event.run(t)
+		end
+
+		to_run
+	end
+
+	def clear!
+		@@events = []
+	end
+end

data/test/clockwork_test.rb

@@ -0,0 +1,50 @@
+require File.dirname(__FILE__) + '/../lib/clockwork'
+require 'contest'
+
+class ClockworkTest < Test::Unit::TestCase
+	setup do
+		Clockwork.clear!
+	end
+
+	def assert_will_run(t)
+		assert_equal 1, Clockwork.tick(t).size
+	end
+
+	def assert_wont_run(t)
+		assert_equal 0, Clockwork.tick(t).size
+	end
+
+	test "once a minute" do
+		Clockwork.every('1m') { }
+
+		assert_will_run(t=Time.now)
+		assert_wont_run(t+30)
+		assert_will_run(t+60)
+	end
+
+	test "every three minutes" do
+		Clockwork.every('3m') { }
+
+		assert_will_run(t=Time.now)
+		assert_wont_run(t+2*60)
+		assert_will_run(t+3*60)
+	end
+
+	test "once an hour" do
+		Clockwork.every('1h') { }
+
+		assert_will_run(t=Time.now)
+		assert_wont_run(t+30*60)
+		assert_will_run(t+60*60)
+	end
+
+	test "once a day at 16:20" do
+		Clockwork.every('1d', :at => '16:20') { }
+
+		assert_wont_run Time.parse('jan 1 2010 16:19:59')
+		assert_will_run Time.parse('jan 1 2010 16:20:00')
+		assert_wont_run Time.parse('jan 1 2010 16:20:01')
+		assert_wont_run Time.parse('jan 2 2010 16:19:59')
+		assert_will_run Time.parse('jan 2 2010 16:20:00')
+	end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification 
+name: clockwork
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Adam Wiggins
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-11 00:00:00 -07:00
+default_executable: clockwork
+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
+has_rdoc: true
+homepage: http://github.com/adamwiggins/clockwork
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: clockwork
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A scheduler process to replace cron.
+test_files: 
+- test/clockwork_test.rb