unicron 0.1.0

data/lib/unicron.rb

@@ -0,0 +1,30 @@
+##
+# Unicron provides a simple mechanism for scheduling one-off and repeating tasks
+# to execute at specific times in the background of a long-running Ruby process.
+#
+# Tasks are represented as Job instances added to a JobQueue. A Schedule
+# manages a single background thread which pops items off the JobQueue and runs
+# them one at a time. Unicron manages a default Schedule for simplicity, but it
+# is safe to create more - each will run its own thread with its own JobQueue.
+# Since a Schedule only runs one Job at a time, a Job that is blocked or
+# processing could potentially delay other Jobs on the same Schedule. For that
+# reason, you may want to use a separate Schedule for long-running tasks.
+#
+module Unicron
+  autoload :Job,      'unicron/job'
+  autoload :JobQueue, 'unicron/job_queue'
+  autoload :Schedule, 'unicron/schedule'
+
+  ## Provide access to the default Unicron Schedule.
+  def self.default_schedule
+    @@default_schedule ||= Schedule.new
+  end
+
+  ##
+  # Create a new Job and add it to the default Schedule. See Job::new for
+  # available options.
+  #
+  def self.schedule options={}, &block
+    default_schedule.schedule options, &block
+  end
+end

data/lib/unicron/job.rb

@@ -0,0 +1,148 @@
+##
+# Job contains all of the information pertinent to a particular task that can be
+# managed by Unicron.
+#
+class Unicron::Job
+
+  ## Time of the first run of this Job.
+  attr_reader :at
+
+  ## Set the time of the first run of this Job.
+  def at= value
+    self.options = {at: value}
+  end
+
+  ##
+  # True if a cancellation is pending. Only meaningful while the Job is running.
+  #
+  attr_reader :cancelled
+
+  ## Time before the first run, and between repeats of this Job.
+  attr_reader :delay
+
+  ## Set the time before the first run, and between repeats of this Job.
+  def delay= value
+    self.options = {delay: value}
+  end
+
+  ## Time of the next Job run.
+  attr_reader :next_run
+
+  ## Time of the previous Job run.
+  attr_reader :previous_run
+
+  ## The number of times to repeat, or true for an infinitely repeating Job.
+  attr_reader :repeat
+
+  ## Set the number of times to repeat, or true for an infinitely repeating Job.
+  def repeat= value
+    self.options = {repeat: value}
+  end
+
+  ## Proc that gets called when the Job is run.
+  attr_reader :task
+
+  ## Set the Proc that gets called when the Job is run.
+  def task= value
+    self.options = {task: value}
+  end
+
+  ## Compare two Job instances chronologically by time of next run.
+  def <=> other
+    next_run <=> other.next_run
+  end
+
+  ## Deschedules the Job.
+  def cancel
+    if queue
+      queue.delete self
+    else
+      @cancelled = true
+    end
+  end
+
+  ##
+  # Create a new Job. The code to run can be specified either as a block to the
+  # constructor or as an option named +task+. If both are specified, the option
+  # takes precedence over the block.
+  #
+  # For non-repeating Jobs, you must use either +at+ or +delay+ to specify when
+  # the Job should be run. If +at+ is specified, the job will run at that time
+  # (or immediately, if +at+ is in the past). If +delay+ is specified, it will
+  # run that number of seconds after it is scheduled.
+  #
+  # For repeating Jobs, set +repeat+ to the number of times to repeat the Job,
+  # or +true+ to repeat infinitely. The +delay+ option becomes mandatory and
+  # specifies the number of seconds between invocations. If the +at+ option is
+  # specified, it gives the time of the first invocation; otherwise, it first
+  # fires +delay+ seconds in the future.
+  #
+  # For both repeating and non-repeating jobs, if both +at+ and +delay+ are
+  # specified, and +at+ is in the past, the first invocation will occur at the
+  # first even multiple of +delay+ seconds after +at+. This provides an easy way
+  # of ensuring that the jobs are run at the same time every hour or day.
+  #
+  def initialize options={}, &task
+    self.options = options.merge task: task
+  end
+
+  ## Return a Hash of this Job's options.
+  def options
+    {at: at, delay: delay, repeat: repeat, task: task}
+  end
+
+  ##
+  # Set many Job options at once.
+  #
+  def options= value
+    notify_queue = !queue.nil? && [:at, :delay].any? {|k| value.has_key? k}
+    value = {at: at, delay: delay, repeat: repeat, task: task}.merge! value
+    if value[:task].nil?
+      raise ArgumentError, 'No task specified.'
+    end
+    if value[:at].nil? && value[:delay].nil?
+      raise ArgumentError, 'Either at or delay must be specified.'
+    end
+    if value[:repeat] && value[:delay].nil?
+      raise ArgumentError, 'Repeating jobs must specify delay.'
+    end
+    @at = value[:at]
+    @delay = value[:delay]
+    @repeat = value[:repeat]
+    @task = value[:task]
+    queue.send :jobs_changed if notify_queue
+    value
+  end
+
+  ##
+  # Runs the Job, yielding self.
+  #
+  def run
+    self.repeat -= 1 if repeat.is_a? Numeric
+    task.call self
+    @previous_run = next_run
+  end
+
+  protected
+    ## JobQueue that this Job is scheduled on. (Protected)
+    attr_reader :queue
+
+    ##
+    # Set the JobQueue that this Job is scheduled on.
+    #
+    def queue= value
+      @cancelled = false
+      @queue = value
+      if queue
+        now = Time.now
+        base = at || previous_run
+        @next_run = if base.nil?
+          now + delay
+        elsif delay.nil? || base >= now
+          base
+        else
+          base + ((now - base) / delay).ceil * delay
+        end
+      end
+    end
+end

data/lib/unicron/job_queue.rb

@@ -0,0 +1,69 @@
+require 'monitor'
+
+##
+# JobQueue manages a set of Job instances for a Schedule. Users of Unicron
+# should not have to deal directly with JobQueue instances.
+#
+class Unicron::JobQueue < Monitor
+
+  ## Add a Job to the JobQueue.
+  def << job
+    synchronize do
+      unless @jobs.include? job
+        @jobs << job
+        job.send :queue=, self
+        jobs_changed
+      end
+      self
+    end
+  end
+
+  ## Delete a Job from the JobQueue.
+  def delete job
+    synchronize do
+      if @jobs.include? job
+        job.send :queue=, nil
+        @jobs.delete job
+        jobs_changed
+      end
+      job
+    end
+  end
+
+  ## Create an empty JobQueue.
+  def initialize
+    super
+    @jobs = []
+    @jobs_changed = new_cond
+  end
+
+  ##
+  # Return the next Job in the JobQueue, sorted chronologically, no earlier than
+  # its appointed time. This call will block until the next Job is ready. If the
+  # JobQueue is empty, it will block until a Job is added and that Job becomes
+  # ready.
+  #
+  def pop
+    synchronize do
+      while true
+        @jobs_changed.wait_while {@jobs.empty?}
+        job = @jobs.first
+        delay = job.next_run - Time.now
+        break if delay <= 0
+        @jobs_changed.wait delay
+      end
+      job.send :queue=, nil
+      @jobs.delete job
+    end
+  end
+
+  protected
+
+    ## Notify a blocked thread that it should check the queue contents again.
+    def jobs_changed
+      synchronize do
+        @jobs.sort!
+        @jobs_changed.signal
+      end
+    end
+end

data/lib/unicron/schedule.rb

@@ -0,0 +1,59 @@
+##
+# Schedule manages a JobQueue which contains Job instances, and a thread which
+# pops and executes them. For simplicity's sake, the Unicron module manages a
+# default Schedule, but you can create and manage your own if necessary. Each
+# uses its own JobQueue and thread, so they will not interfere with each other.
+#
+class Unicron::Schedule
+
+  ##
+  # Add a Job to the Schedule's JobQueue.
+  #
+  def << job
+    @queue << job
+    self
+  end
+
+  ##
+  # Create a new, empty Schedule. The Schedule's thread is started and blocks
+  # immediately, waiting for a Job to be added.
+  #
+  def initialize
+    @queue = Unicron::JobQueue.new
+    @thread = Thread.new &method(:run)
+  end
+
+  ##
+  # Create a new Job and add it to the Schedule. See Job::new for available
+  # options.
+  #
+  def schedule options={}, &block
+    job = Unicron::Job.new options, &block
+    self << job
+    job
+  end
+
+  protected
+
+    ##
+    # Loops infinitely, popping jobs off the JobQueue and running it. All
+    # exceptions are caught and logged to STDERR so that they do not interfere
+    # with other jobs. If the Job is repeating, it is added back to the JobQueue
+    # after it completes, regardless of whether it raised an exception.
+    #
+    def run
+      while job = @queue.pop
+        begin
+          job.run
+        rescue => err
+          puts STDERR, (["#{err.class}: #{err.message}"] +
+              err.backtrace.collect {|i| "from #{i}"}).join("\n\t")
+        end
+        if !job.cancelled &&
+            ((job.repeat.is_a?(Numeric) && job.repeat > 0) ||
+            (!job.repeat.is_a?(Numeric) && job.repeat))
+          self << job
+        end
+      end
+    end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: unicron
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- David P Kleinschmidt
+- Ian C. Anderson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-18 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &83620100 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.7.0
+  type: :development
+  prerelease: false
+  version_requirements: *83620100
+description: Schedules one-off and repeating background tasks within long-running
+  ruby processes.
+email: david@kleinschmidt.name
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/unicron.rb
+- lib/unicron/schedule.rb
+- lib/unicron/job_queue.rb
+- lib/unicron/job.rb
+homepage: http://github.com/zobar/unicron
+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: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Schedule background tasks.
+test_files: []