allora 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in allora.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Flippa.com Pty. Ltd.
+
+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

@@ -0,0 +1,184 @@
+# Allora: A distributed cron daemon in ruby
+
+Allora (*Italian: at that time*) allows you to run a cron scheduler (yes, the actual
+scheduler) on multiple machines within a network, without the worry of multiple
+machines processing the same job on the schedule.
+
+A centralized backend is used (by default redis) in order to maintain a shared state.
+Allora also provides a basic in-memory backend, which can be used to expressly allow
+jobs to run on more than one machine (e.g. to perform some file cleanup operations
+directly on the machine).
+
+I am a firm believer in keeping it simple, so you'll find Allora weighs in at just
+a couple of hundred SLOC and doesn't provide a bajillion features you aren't likely
+to use.
+
+Schedules are written in pure ruby, not YAML.
+
+The scheduler process is reentrant.  That is to say, if the scheduler is due to run
+a job at midnight and the process is stopped at 23:59, then restarted at 00:01, the
+midnight job will still run.  Reentry is smart, however: it catches back up as soon
+as it has processed any overdue jobs (so it doesn't get stuck in the past).
+
+## Installation
+
+Via rubygems:
+
+    gem install allora
+
+## Creating a schedule
+
+The schedule is a ruby file.  You execute this ruby file to start the daemon running.
+
+If you don't have ActiveSupport available, replace `1.hour`, for example with `3600`
+(seconds).
+
+Create a file, for example "schedule.rb":
+
+    Allora.start(:join => true) do |s|
+      # a job that runs hourly
+      s.add("empty_cache", :every => 1.hour) { `rm -f /path/to/cache/*` }
+      
+      # a job that runs based on a cron string
+      s.add("update_stats", :cron => "0 2,14 * * *") { Resque.enqueue(UpdateStatsJob) }
+    end
+
+When you run this file with ruby, it will remain in the foreground, providing log
+output.  It is *currently* your responsibility to daemonize the process.
+
+Note that in the above example, we're only using the in-memory backend, so this
+probably shouldn't be run on multiple machines.
+
+In the following example, we specify to use a Redis backend, which is safe to run on
+multiple machines:
+
+    Allora.start(:backend => :redis, :host => "redis.lan", :join => true) do |s|
+      # a job that runs hourly
+      s.add("empty_cache", :every => 1.hour) { `rm -f /path/to/cache/*` }
+      
+      # a job that runs based on a cron string
+      s.add("update_stats", :cron => "0 2,14 * * *") { Resque.enqueue(UpdateStatsJob) }
+    end
+
+We specify a redis host (and port) so that schedule data can be shared.
+
+## Accessing your application environment
+
+Allora will not make any assumptions about your application.  It is your responsibility
+to load it, if you need it.  For Rails 3.x applications, add the following to the top
+of your schedule:
+
+    require File.expand_path("../config/environment", __FILE__)
+
+Assuming "../config/environment" resolves to the actual path where your environment.rb is
+found.
+
+## Implementation notes
+
+Disclaimer: The scheduler is not intended to be 100% accurate.  A job set to run every
+second will probably run every second, but occasionally, if polling is slow, 2 seconds
+may pass between runs.  If this is a problem for your application, you should not use
+this gem.  The focus of this gem is to support running the scheduler on multiple machines.
+
+In order to run the scheduler on more than one machine, Allora uses a `Backend` class to
+maintain state.  The timestamp at which a job should next run is kept in the backend.
+When the scheduler polls, it asks the backend to return any jobs that can be run *and*
+update the time at which they should next run.  A locking strategy is used to ensure no
+two machines update the schedule information at the same time.
+
+In short, whichever running scheduler finds a job to do is the same scheduler the sets the
+next time that job should run.
+
+Jobs are executed in forked children, so that if they crash, the scheduler does not
+exit.
+
+## Custom Job classes
+
+Allora offers two types of Job, which make sense for scheduling work at set intervals.
+These are the `:every` and `:cron` types of job, which map to `Allora::Job::EveryJob` and
+`Allora::Job::CronJob` internally.  You may write your own subclass of `Allora::Job`, if
+you have some specific need that is not met by either of these job types.
+
+Job classes simply need to implement the `#next_at` method, which accepts a `Time` as
+input and returns a time after that at which the job should run.  `Allora::Job` will
+handle the execution of the job itself.
+
+Here's the implementation of the `EveryJob` class:
+
+    module Allora
+      class Job::EveryJob < Job
+        def initialize(n, &block)
+          @duration = n
+
+          super(&block)
+        end
+
+        def next_at(from_time)
+          from_time + @duration
+        end
+      end
+    end
+
+Quite simply it adds whatever the duration is to the given time.
+
+To use your custom Job class, pass the instance to `Scheduler#add`:
+
+    s.add("foo", MyJob.new { puts "Running custom job" })
+
+## Custom Backend classes
+
+It is more likely that you will wish to write a custom backend, than a custom job.  In
+particular if you do not wish to use Redis, which is currently the only provided option.
+
+Backend classes subclass `Allora::Backend` and implement `#reschedule`.  The `#reschedule`
+method accepts a Hash of jobs to check and does two things:
+
+  1. Returns a new Hash containing any jobs that can run now
+  2. Internally updates the time at which the job should next run
+
+A locking strategy should be used in order to ensure the backend supports running on
+multiple machines.
+
+For the sake of clarity and brevity, here is a pseudo-code example:
+
+    class MyBackend < Allora::Backend
+      def reschedule(jobs)
+        now = Time.now
+        jobs.select do |name, job|
+          schedule_if_new(name, job.next_at(now))
+          lock_job(name) do # returns the result of the block only if successful
+            next_run = scheduled_time(name)
+            if next_run <= now
+              update_schedule(name, job.next_at(now))
+              true
+            else
+              false
+            end
+          end
+        end
+      end
+    end
+
+The backend sets a new time into its internal schedule if none is present for that job.
+
+It then tries to gain a lock on the schedule information for that job, returning false
+if not possible (and thus not selecting the job from the input Hash).
+
+If a lock was acquired, the time at which the job should run is checked.  If it is in the
+past, the scheule information is advanced to the next time at which the job should run and
+the job is selected, else the job is not selected.
+
+## Credits
+
+Big thanks for jmettraux for rufus-scheduler, which I have borrowed the cron parsing logic
+from.
+
+## Disclaimer
+
+Most of this work is the result of a quick code spike on a Sunday afternoon.  There are no
+specs right now.  Use at your own risk.  I will add specs in the next day or two, if you
+prefer to wait.
+
+## Copyright & License
+
+Copyright &copy; 2012 Flippa.com Pty. Ltd. See LICENSE file for details.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/allora.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "allora/version"
+
+Gem::Specification.new do |s|
+  s.name        = "allora"
+  s.version     = Allora::VERSION
+  s.authors     = ["d11wtq"]
+  s.email       = ["chris@w3style.co.uk"]
+  s.homepage    = "https://github.com/flippa/allora"
+  s.summary     = %q{A ruby scheduler that keeps it simple, with support for distributed schedules}
+  s.description = %q{Allora (Italian for "at that time") provides a replacement for the classic UNIX
+                     cron, using nothing but ruby.  It is very small, easy to follow and relatively
+                     feature-light.  It does support a locking mechanism, backed by Redis, or any
+                     other custom implementation, which makes it possible to run the scheduler on
+                     more than one server, without worrying about jobs executing more than once per
+                     scheduled time.}
+
+  s.rubyforge_project = "allora"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "redis"
+end

data/lib/allora/backend/memory.rb

@@ -0,0 +1,50 @@
+##
+# 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.
+#
+# Copyright © 2012 Flippa.com Pty. Ltd.
+##
+
+module Allora
+  # A basic, single-process backend using a Hash.
+  #
+  # You should not run this on multiple machines on the same network.
+  class Backend::Memory < Backend
+    # Initialize a new Memory backend.
+    #
+    # @params [Hash] opts
+    #   this backend does not accept any options
+    def initialize(opts = {})
+      super
+
+      @schedule = {}
+    end
+
+    def reschedule(jobs)
+      current_time = Time.now
+      last_time    = (@last_time ||= Time.now)
+      @last_time   = current_time
+
+      jobs.select do |name, job|
+        @schedule[name] ||= job.next_at(last_time)
+        @schedule[name] < current_time && @schedule[name] = job.next_at(current_time)
+      end
+    end
+  end
+end

data/lib/allora/backend/redis.rb

@@ -0,0 +1,126 @@
+##
+# 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.
+#
+# Copyright © 2012 Flippa.com Pty. Ltd.
+##
+
+module Allora
+  # A backend that uses Redis to maintain schedule state.
+  #
+  # When using this backend, it is possible to run the scheduler process
+  # on more than one machine in the network, connected to the same Redis
+  # instace. Whichever scheduler finds a runnable job first updates the
+  # 'next run time' information in Redis, using an optimistic locking
+  # strategy, then executes the job if the write succeeds.  No two
+  # machines will ever run the same job twice.
+  class Backend::Redis < Backend
+    attr_reader :redis
+    attr_reader :prefix
+
+    # Initialize the Redis backed with the given options.
+    #
+    # Options:
+    #   client: an already instantiated Redis client object.
+    #   host:   the hostname of a Redis server
+    #   port:   the port number of a Redis server
+    #   prefix: a namespace prefix to use
+    #
+    # @param [Hash] opts
+    #   options for the Redis backend
+    def initialize(opts = {})
+      @redis  = create_redis(opts)
+      @prefix = opts.fetch(:prefix, "allora")
+
+      reset!
+    end
+
+    def reschedule(jobs)
+      current_time = Time.now
+      last_time    = send(:last_time)
+      set_last_time(current_time)
+
+      jobs.select do |name, job|
+        redis.hsetnx(schedule_info_key, name, 1)
+        redis.setnx(job_info_key(name), time_to_int(job.next_at(last_time)))
+        update_job_info(job, name, current_time)
+      end
+    end
+
+    private
+
+    def create_redis(opts)
+      return opts[:client] if opts.key?(:client)
+
+      ::Redis.new(:host => opts.fetch(:host, "localhost"), :port => opts.fetch(:port, 6379))
+    end
+
+    # Forces all job data to be re-entered into Redis at the next poll
+    def reset!
+      redis.hgetall(schedule_info_key) { |name, t| redis.del(job_info_key(name)) }
+      redis.del(schedule_info_key)
+    end
+
+    # Returns a Boolean specifying if the job can be run and no race condition occurred updating its info
+    def update_job_info(job, name, time)
+      redis.watch(job_info_key(name))
+      run_at = int_to_time(redis.get(job_info_key(name)))
+
+      if run_at <= time
+        redis.multi
+        redis.set(job_info_key(name), time_to_int(job.next_at(time)))
+        redis.exec
+      else
+        redis.unwatch && false
+      end
+    end
+
+    def schedule_info_key
+      "#{prefix}_schedule"
+    end
+
+    def job_info_key(name)
+      "#{prefix}_job_#{name}"
+    end
+
+    def last_time_key
+      "#{prefix}_last_run"
+    end
+
+    # Returns the last time at which polling occurred
+    #
+    # This is used as a re-entry mechanism if the scheduler stops
+    def last_time
+      redis.setnx(last_time_key, time_to_int(Time.now))
+      int_to_time(redis.get(last_time_key))
+    end
+
+    def set_last_time(t)
+      redis.set(last_time_key, time_to_int(t))
+    end
+
+    def time_to_int(t)
+      t.to_i
+    end
+
+    def int_to_time(i)
+      Time.at(i.to_i)
+    end
+  end
+end

data/lib/allora/backend.rb

@@ -0,0 +1,52 @@
+##
+# 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.
+#
+# Copyright © 2012 Flippa.com Pty. Ltd.
+##
+
+module Allora
+  class Backend
+    attr_reader :options
+
+    # Initialize the backend with the given options Hash.
+    #
+    # @param [Hash] opts
+    #   options for the backend, if the backend requires any
+    def initialize(opts = {})
+      @options = opts
+    end
+
+    # Reschedules jobs in the given Hash and returns those that should run now.
+    #
+    # Subclasses should take an approach that tracks the run time information and updates
+    # it in a way that avoids race conditions.  The job should not be run until it can be
+    # guaranteed that it has been rescheduled for a future time and no other scheduler
+    # process executed the job first.
+    #
+    # @param [Hash] jobs
+    #   a Hash mapping job names with their job classes
+    #
+    # @return [Hash]
+    #   a Hash containing the jobs to be run now, if any
+    def reschedule(jobs)
+      raise NotImplementedError, "Abstract method #reschedule must be implemented by subclass"
+    end
+  end
+end

data/lib/allora/cron_line.rb

@@ -0,0 +1,244 @@
+#--
+# Copyright (c) 2006-2012, John Mettraux, jmettraux@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.
+#
+# Made in Japan.
+#++
+
+# This is almost entirely lifted from https://github.com/jmettraux/rufus-scheduler/blob/master/lib/rufus/sc/cronline.rb
+module Allora
+  # Parses a crontab string to determine the times it represents.
+  class CronLine
+    attr_reader :seconds
+    attr_reader :minutes
+    attr_reader :hours
+    attr_reader :days
+    attr_reader :months
+    attr_reader :weekdays
+    attr_reader :monthdays
+    attr_reader :timezone
+
+    def initialize(line)
+      items = line.split
+
+      raise ArgumentError.new("not a valid cronline : '#{line}'") \
+        unless items.length == 5 or items.length == 6
+
+      offset = items.length - 5
+
+      @seconds = offset == 1 ? parse_item(items[0], 0, 59) : [0]
+      @minutes = parse_item(items[0 + offset], 0, 59)
+      @hours   = parse_item(items[1 + offset], 0, 24)
+      @days    = parse_item(items[2 + offset], 1, 31)
+      @months  = parse_item(items[3 + offset], 1, 12)
+
+      @weekdays, @monthdays = parse_weekdays(items[4 + offset])
+    end
+
+    # Returns the next time that this cron line is supposed to 'fire'
+    #
+    # Note that the time instance returned will be in the same time zone that
+    # the given start point Time (thus a result in the local time zone will
+    # be passed if no start time is specified (search start time set to
+    # Time.now))
+    #
+    # @example
+    #
+    #   Allora::CronLine.new('30 7 * * *').next_time(
+    #     Time.mktime(2008, 10, 24, 7, 29))
+    #   #=> Fri Oct 24 07:30:00 -0500 2008
+    #
+    #   Allora::CronLine.new('30 7 * * *').next_time(
+    #     Time.utc(2008, 10, 24, 7, 29))
+    #   #=> Fri Oct 24 07:30:00 UTC 2008
+    #
+    #   Allora::CronLine.new('30 7 * * *').next_time(
+    #     Time.utc(2008, 10, 24, 7, 29)).localtime
+    #   #=> Fri Oct 24 02:30:00 -0500 2008
+    #
+    # @param [Time] time
+    #   the time from which to compute the next time
+    #
+    # @return [Time]
+    #   the next time after the given Time
+    def next_time(time)
+      # little adjustment before starting
+      time = time + 1
+
+      loop do
+        unless date_match?(time)
+          time += (24 - time.hour) * 3600 - time.min * 60 - time.sec
+          next
+        end
+        unless sub_match?(time.hour, @hours)
+          time += (60 - time.min) * 60 - time.sec
+          next
+        end
+        unless sub_match?(time.min, @minutes)
+          time += 60 - time.sec
+          next
+        end
+        unless sub_match?(time.sec, @seconds)
+          time += 1
+          next
+        end
+
+        break
+      end
+
+      time
+    end
+
+    def to_array
+      [
+        @seconds,
+        @minutes,
+        @hours,
+        @days,
+        @months,
+        @weekdays,
+        @monthdays
+      ]
+    end
+
+    private
+
+    WEEKDAYS = %w[ sun mon tue wed thu fri sat ]
+
+    def parse_weekdays(item)
+      return nil if item == '*'
+
+      items = item.downcase.split(',')
+
+      weekdays = nil
+      monthdays = nil
+
+      items.each do |it|
+        if it.match(/#[12345]$/)
+          raise ArgumentError.new(
+            "ranges are not supported for monthdays (#{it})"
+          ) if it.index('-')
+
+          (monthdays ||= []) << it
+        else
+          WEEKDAYS.each_with_index { |a, i| it.gsub!(/#{a}/, i.to_s) }
+
+          its = it.index('-') ? parse_range(it, 0, 7) : [Integer(it)]
+          its = its.collect { |i| i == 7 ? 0 : i }
+
+          (weekdays ||= []).concat(its)
+        end
+      end
+
+      weekdays = weekdays.uniq if weekdays
+
+      [weekdays, monthdays]
+    end
+
+    def parse_item(item, min, max)
+      return nil                         if item == '*'
+      return parse_list(item, min, max)  if item.index(',')
+      return parse_range(item, min, max) if item.index('*') or item.index('-')
+
+      i = item.to_i
+
+      i = min if i < min
+      i = max if i > max
+
+      [i]
+    end
+
+    def parse_list(item, min, max)
+      item.split(',').inject([]) { |r, i|
+        r.push(parse_range(i, min, max))
+      }.flatten
+    end
+
+    def parse_range(item, min, max)
+      i = item.index('-')
+      j = item.index('/')
+
+      return item.to_i if (not i and not j)
+
+      inc = j ? item[j + 1..-1].to_i : 1
+
+      istart = -1
+      iend = -1
+
+      if i
+        istart = item[0..i - 1].to_i
+        iend   = if j
+          item[i + 1..j - 1].to_i
+        else
+          item[i + 1..-1].to_i
+        end
+      else # case */x
+        istart = min
+        iend = max
+      end
+
+      istart = min if istart < min
+      iend   = max if iend > max
+
+      result = []
+
+      value = istart
+      loop do
+        result << value
+        value = value + inc
+        break if value > iend
+      end
+
+      result
+    end
+
+    def sub_match?(value, values)
+      values.nil? || values.include?(value)
+    end
+
+    def monthday_match(monthday, monthdays)
+      return true if monthdays == nil
+      return true if monthdays.include?(monthday)
+    end
+
+    def date_match?(date)
+      return false unless sub_match?(date.day, @days)
+      return false unless sub_match?(date.month, @months)
+      return false unless sub_match?(date.wday, @weekdays)
+      return false unless sub_match?(CronLine.monthday(date), @monthdays)
+      true
+    end
+
+    DAY_IN_SECONDS = 7 * 24 * 3600
+
+    def self.monthday(date)
+      count = 1
+      date2 = date.dup
+
+      loop do
+        date2 = date2 - DAY_IN_SECONDS
+        break if date2.month != date.month
+        count = count + 1
+      end
+
+      "#{WEEKDAYS[date.wday]}##{count}"
+    end
+  end
+end

data/lib/allora/job/cron_job.rb

@@ -0,0 +1,46 @@
+##
+# 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.
+#
+# Copyright © 2012 Flippa.com Pty. Ltd.
+##
+
+module Allora
+  # A classic cron style job, with support for seconds.
+  class Job::CronJob < Job
+    # Initialize the CronJob with the given cron string.
+    #
+    # @param [String] cron_str
+    #   any valid cron string, which may include seconds
+    #
+    # @example
+    #   CronJob.new("*/5 * * * * *") # every 5s
+    #   CronJob.new("0,30 * * * *")  # the 0th and 30th min of each hour
+    #   CronJob.new("0 3-6 * * *")   # on the hour, every hour between 3am and 6am
+    def initialize(cron_str, &block)
+      super(&block)
+
+      @cron_line = CronLine.new(cron_str)
+    end
+
+    def next_at(from_time)
+      @cron_line.next_time(from_time)
+    end
+  end
+end

data/lib/allora/job/every_job.rb

@@ -0,0 +1,48 @@
+##
+# 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.
+#
+# Copyright © 2012 Flippa.com Pty. Ltd.
+##
+
+module Allora
+  # A very simple job type that simply repeats every +n+ seconds.
+  class Job::EveryJob < Job
+    # Initialize the job to run every +n+ seconds.
+    #
+    # @param [Integer] n
+    #   the number of seconds to wait between executions
+    #
+    # You may use ActiveSupport's numeric helpers, if you have ActiveSupport
+    # available.
+    #
+    # @example Using ActiveSupport
+    #   EveryJob.new(15.seconds) { puts "Boo!" }
+    #
+    def initialize(n, &block)
+      @duration = n
+
+      super(&block)
+    end
+
+    def next_at(from_time)
+      from_time + @duration
+    end
+  end
+end

data/lib/allora/job.rb

@@ -0,0 +1,57 @@
+##
+# 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.
+#
+# Copyright © 2012 Flippa.com Pty. Ltd.
+##
+
+module Allora
+  # Abstract job class providing a wrapper around job execution.
+  #
+  # Subclasses must be able to provide a time for the job to run,
+  # given a start time.
+  class Job
+    attr_reader :block
+
+    # Initialize the job with the given block to invoke during execution.
+    def initialize(&block)
+      @block = block
+    end
+
+    # Execute the job.
+    #
+    # Execution happens inside a forked and detached child.
+    def execute
+      Process.detach(fork { @block.call })
+    end
+
+    # Returns the next time at which this job should run.
+    #
+    # Subclasses must implement this method.
+    #
+    # @param [Time] from_time
+    #   the time from which to calculate the next run time
+    #
+    # @return [Time]
+    #   the time at which the job should next run
+    def next_at(from_time)
+      raise NotImplementedError, "Abstract method #next_at must be overridden by subclasses"
+    end
+  end
+end

data/lib/allora/scheduler.rb

@@ -0,0 +1,130 @@
+##
+# 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.
+#
+# Copyright © 2012 Flippa.com Pty. Ltd.
+##
+
+module Allora
+  # Worker daemon, dealing with a Backend to execute jobs at regular intervals.
+  class Scheduler
+    attr_reader :jobs
+    attr_reader :backend
+
+    # Initialize the Scheduler with the given options.
+    #
+    # Options:
+    #   backend:  an instance of any Backend class (defaults to Memory)
+    #   interval: a floating point specifying how frequently to poll (defaults to 0.333)
+    #   logger:   an instance of a ruby Logger, or nil to disable
+    #   *other:   any additonal parameters are passed to the Backend
+    #
+    # @param [Hash] options
+    #   options for the scheduler, if any
+    def initialize(opts = {})
+      require "logger"
+
+      @backend  = create_backend(opts)
+      @interval = opts.fetch(:interval, 0.333)
+      @logger   = opts.fetch(:logger, Logger.new(STDOUT))
+      @jobs     = {}
+    end
+
+    # Register a new job for the given options.
+    #
+    # @example
+    #   s.add("foo", :every => 5.seconds) { puts "Running!" }
+    #   s.add("bar", :cron => "*/15 * 1,10,20 * *") { puts "Bonus!" }
+    #
+    # @param [String] name
+    #   a unique name to give this job (used for locking)
+    #
+    # @param [Hash, Job] opts_or_job
+    #   options specifying when to run the job (:every, or :cron), or a Job instance.
+    #
+    # @return [Job]
+    #   the job instance added to the schedule
+    def add(name, opts_or_job, &block)
+      jobs[name.to_s] = create_job(opts_or_job, &block)
+    end
+
+    # Starts running the scheduler in a new Thread, and returns that Thread.
+    #
+    # @return [Thread]
+    #   the scheduler polling Thread
+    def start
+      log "Starting scheduler process, using #{@backend.class}"
+
+      @thread = Thread.new do
+        loop do
+          @backend.reschedule(@jobs).each do |name, job|
+            log "Running job '#{name}'"
+            job.execute
+          end
+
+          sleep(@interval)
+        end
+      end
+    end
+
+    # Stop the currently running scheduler Thread
+    def stop
+      log "Exiting scheduler process"
+      @thread.exit
+    end
+
+    # Join the currently running scheduler Thread.
+    #
+    # This should be invoked to prevent the parent Thread from terminating.
+    def join
+      @thread.join
+    end
+
+    private
+
+    def create_job(opts, &block)
+      return opts if Job === opts
+
+      raise ArgumentError "Missing schedule key (either :cron, or :every)" \
+        unless opts.key?(:cron) || opts.key?(:every)
+
+      if opts.key?(:every)
+        Job::EveryJob.new(opts[:every], &block)
+      elsif opts.key?(:cron)
+        Job::CronJob.new(opts[:cron], &block)
+      end
+    end
+
+    def create_backend(opts)
+      return Backend::Memory.new unless opts.key?(:backend)
+
+      case opts[:backend]
+        when :memory then Backend::Memory.new
+        when :redis  then Backend::Redis.new(opts)
+        when Class   then opts[:backend].new(opts)
+        when Backend then opts[:backend]
+        else raise "Unsupported backend '#{opts[:backend].inspect}'"
+      end
+    end
+
+    def log(str)
+      @logger.info("Allora: #{str}") if @logger
+    end
+  end
+end

data/lib/allora/version.rb

@@ -0,0 +1,26 @@
+##
+# 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.
+#
+# Copyright © 2012 Flippa.com Pty. Ltd.
+##
+
+module Allora
+  VERSION = "0.0.1"
+end

data/lib/allora.rb

@@ -0,0 +1,57 @@
+##
+# 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.
+#
+# Copyright © 2012 Flippa.com Pty. Ltd.
+##
+
+require "allora/version"
+
+require "allora/scheduler"
+
+require "allora/backend"
+require "allora/backend/memory"
+require "allora/backend/redis"
+
+require "allora/cron_line"
+
+require "allora/job"
+require "allora/job/every_job"
+require "allora/job/cron_job"
+
+module Allora
+  class << self
+    # Create a new Scheduler, yield it and then start it.
+    #
+    # If the `:join` option is specified, the scheduler Thread is joined.
+    #
+    # @params [Hash] opts
+    #   options specifying a Backend to use, and any backend-specific options
+    #
+    # @return [Scheduler]
+    #   the running scheduler
+    def start(opts = {})
+      Scheduler.new(opts).tap do |s|
+        yield s
+        s.start
+        s.join if opts[:join]
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: allora
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- d11wtq
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: &70298724477660 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70298724477660
+description: ! "Allora (Italian for \"at that time\") provides a replacement for the
+  classic UNIX\n                     cron, using nothing but ruby.  It is very small,
+  easy to follow and relatively\n                     feature-light.  It does support
+  a locking mechanism, backed by Redis, or any\n                     other custom
+  implementation, which makes it possible to run the scheduler on\n                     more
+  than one server, without worrying about jobs executing more than once per\n                     scheduled
+  time."
+email:
+- chris@w3style.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- allora.gemspec
+- lib/allora.rb
+- lib/allora/backend.rb
+- lib/allora/backend/memory.rb
+- lib/allora/backend/redis.rb
+- lib/allora/cron_line.rb
+- lib/allora/job.rb
+- lib/allora/job/cron_job.rb
+- lib/allora/job/every_job.rb
+- lib/allora/scheduler.rb
+- lib/allora/version.rb
+homepage: https://github.com/flippa/allora
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: allora
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: A ruby scheduler that keeps it simple, with support for distributed schedules
+test_files: []
+has_rdoc: