ncr-background_fu 1.0.2

data/History.txt

@@ -0,0 +1,16 @@
+=== 1.0.2 / 2008-05-27
+
+* Fiddling with gemspec to make it work on GitHub. [ncr]
+
+=== 1.0.1 / 2008-05-27
+
+* Updaed README with install instructions. [ncr]
+
+=== 1.0.0 / 2008-05-27
+
+* BackgroundFu is now also a gem. You should check Rails 2.1 and the super sexy gems vendoring features!
+
+  * Updated README.txt so now it looks like those from gems. [ncr]
+  * Previous changes before becoming a gem:
+  * 2008-05-12 Added excessive logging and changed default priority to 0 (Negative priorities allowed). [ncr]
+  * 2008-05-11 Added three columns to Job model: priority (execute jobs in priority descending order), start_at (execute jobs after start_at), lock_version (ensure job is executed by a single daemon). [ncr]

data/Manifest.txt

@@ -0,0 +1,27 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+background-fu.gemspec
+generators/background/USAGE
+generators/background/background_generator.rb
+generators/background/templates/background.rb
+generators/background/templates/background_ctl
+generators/background/templates/daemons
+generators/background/templates/daemons.yml
+generators/background/templates/example_monitored_worker.rb
+generators/background/templates/example_worker.rb
+generators/background/templates/migration.rb
+generators/background/templates/scaffold/_job.html.erb
+generators/background/templates/scaffold/_job_deleted.html.erb
+generators/background/templates/scaffold/_progress_indicator.html.erb
+generators/background/templates/scaffold/background_fu.css
+generators/background/templates/scaffold/index.html.erb
+generators/background/templates/scaffold/jobs.html.erb
+generators/background/templates/scaffold/jobs_controller.rb
+generators/background/templates/scaffold/jobs_helper.rb
+init.rb
+lib/background_fu.rb
+lib/background_fu/worker_monitoring.rb
+lib/job.rb
+lib/job/bonus_features.rb

data/README.txt

@@ -0,0 +1,166 @@
+= BackgroundFu
+
+* http://github.com/ncr/background-fu
+* git://github.com/ncr/background-fu.git
+* http://trix.lighthouseapp.com/projects/9809-backgroundfu
+* ncr@trix.pl
+* http://trix.pl
+
+== DESCRIPTION:
+
+Background tasks in Ruby On Rails made dead simple.
+
+== FEATURES/PROBLEMS:
+
+* Running long background tasks outside of request-response cycle.
+* Very easy to setup and fun to use (See examples below). 
+* Clean and straightforward approach (database-based priority queue).
+* Uses database table (migration included) to store jobs reliably.
+* Capistrano tasks included. 
+* Generators with migrations and example views included.
+* Multiple worker daemons available.
+* Easy to deploy in distributed environments.
+* Enables prioritizing and simple scheduling.
+* Optional worker monitoring (good for AJAX progress bars).
+* Proven its stability and reliability in production use.
+
+== SYNOPSIS:
+
+  ruby ./script/generate background
+  rake db:migrate
+  
+  # to run in production mode use RAILS_ENV=production ruby ./script/daemons start
+  ruby ./script/daemons start
+
+  # then try in console:
+    
+  job_id = Job.enqueue!(ExampleWorker, :add, 1, 2).id
+
+  # after few seconds when background daemon completes the job
+
+  Job.find(job_id).result # result of the job should equal 3
+
+== EXAMPLES:
+
+  # In lib/workers/example_worker.rb:
+
+  # Simple, non-monitored worker.
+  class ExampleWorker
+  
+    def add(a, b)
+      a + b
+    end
+
+  end
+
+  # In lib/workers/example_monitored_worker.rb:
+
+  # Remeber to include BackgroundFu::WorkerMonitoring.
+  class ExampleMonitoredWorker
+
+    include BackgroundFu::WorkerMonitoring
+  
+    def long_and_monitored
+      my_progress = 0
+    
+      record_progress(my_progress)
+
+      while(my_progress < 100)
+        my_progress += 1
+        record_progress(my_progress)
+        sleep 1
+      end
+    
+      record_progress(100)
+    end
+  
+  end
+
+  # In a controller:
+
+    def create
+      session[:job_id] = Job.enqueue!(ExampleWorker, :add, 1, 2).id
+      # or try the monitored worker: session[:job_id] = Job.enqueue!(ExampleMonitoredWorker, :long_and_monitored)
+    end
+
+    def show
+      @job    = Job.find(session[:job_id])
+      @result = @job.result if @job.finished?
+      # or check progress if your worker is monitored: @progress = @job.progress
+    end
+  
+    def index
+      @jobs = Job.find(:all)
+    end
+  
+    def destroy
+      Job.find(session[:job_id]).destroy
+    end
+
+== HANDY CAPISTRANO TASKS:
+
+  namespace :deploy do
+
+    desc "Run this after every successful deployment" 
+    task :after_default do
+      restart_background_fu
+    end
+
+  end
+
+  desc "Restart BackgroundFu daemon"
+  task :restart_background_fu do
+    run "RAILS_ENV=production ruby #{current_path}/script/daemons stop"
+    run "RAILS_ENV=production ruby #{current_path}/script/daemons start"
+  end
+  
+== BONUS FEATURES:
+
+There are bonus features available if you set
+ActiveRecord::Base.allow_concurrency = true 
+in your environment.
+
+These features are: 
+ * monitoring progress (perfect for ajax progress bars)
+ * stopping a running worker in a merciful way.
+
+Read the code (short and easy) to discover them.
+
+== REQUIREMENTS:
+
+* rails
+* daemons
+
+== INSTALL:
+
+* As a Rails plugin: ./script/plugin install git://github.com/ncr/background-fu.git
+* As as a gem to be 'vendorized' starting from Rails 2.1: refer to documentation on rake gems:unpack:dependencies.
+
+== CONTRIBUTING:
+
+If you want to help improve this plugin, feel free to contact me. Fork the project on GitHub, implement a feature, send me a pull request.
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) Jacek Becela
+
+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/Rakefile

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'hoe'
+require './lib/background_fu.rb'
+
+Hoe.new('background-fu', BackgroundFu::VERSION) do |p|
+  p.rubyforge_name = 'background-fu'
+  p.developer('Jacek Becela', 'jacek.becela@gmail.com')
+end

data/generators/background/USAGE

@@ -0,0 +1,3 @@
+Examples:
+    ./script/generate background
+    

data/generators/background/background_generator.rb

@@ -0,0 +1,58 @@
+class BackgroundGenerator < Rails::Generator::Base
+
+  default_options :skip_migration => false, :skip_scaffold => false, :skip_examples => false
+
+  def manifest
+    record do |m|
+      unless options[:skip_migration]
+        m.migration_template 'migration.rb', 'db/migrate', :migration_file_name => "create_jobs"
+      end
+
+      m.directory "lib/daemons"
+      m.file 'background.rb',  'lib/daemons/background.rb'
+      m.file 'background_ctl', 'lib/daemons/background_ctl'
+
+      m.directory "lib/workers"
+      
+      unless options[:skip_examples]
+        m.file 'example_worker.rb',           'lib/workers/example_worker.rb'
+        m.file 'example_monitored_worker.rb', 'lib/workers/example_monitored_worker.rb'
+      end
+      
+      m.file 'daemons.yml', 'config/daemons.yml'
+      m.file 'daemons',     'script/daemons'
+      
+      unless options[:skip_scaffold]
+        m.directory 'app/controllers/admin'
+        m.directory 'app/helpers/admin'
+        m.directory 'app/views/admin/jobs'
+        m.directory 'app/views/layouts/admin'
+
+        m.file 'scaffold/jobs_controller.rb', 'app/controllers/admin/jobs_controller.rb'
+        m.file 'scaffold/jobs_helper.rb',     'app/helpers/admin/jobs_helper.rb'
+
+        m.file 'scaffold/index.html.erb',               'app/views/admin/jobs/index.html.erb'
+        m.file 'scaffold/_job.html.erb',                'app/views/admin/jobs/_job.html.erb'
+        m.file 'scaffold/_job_deleted.html.erb',        'app/views/admin/jobs/_job_deleted.html.erb'
+        m.file 'scaffold/_progress_indicator.html.erb', 'app/views/admin/jobs/_progress_indicator.html.erb'
+
+        m.file 'scaffold/jobs.html.erb', 'app/views/layouts/admin/jobs.html.erb'
+
+        m.file "scaffold/background_fu.css", "public/stylesheets/background_fu.css"
+        
+        
+      end
+    end
+  end
+
+  protected
+
+  def add_options!(opt)
+    opt.separator ''
+    opt.separator 'Options:'
+    opt.on("--skip-migration", "Don't generate migration file for this model")                { |v| options[:skip_migration] = v }
+    opt.on("--skip-scaffold",  "Don't generate scaffold controller and views for this model") { |v| options[:skip_scaffold]  = v }
+    opt.on("--skip-examples",  "Don't generate example workers")                              { |v| options[:skip_examples]  = v }
+  end
+
+end

data/generators/background/templates/background.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require File.dirname(__FILE__) + "/../../config/environment"
+
+Signal.trap("TERM") { exit }
+
+if Job.included_modules.include?(Job::BonusFeatures)
+  RAILS_DEFAULT_LOGGER.info("BackgroundFu: Starting daemon (bonus features enabled).")
+else
+  RAILS_DEFAULT_LOGGER.info("BackgroundFu: Starting daemon (bonus features disabled).")
+end
+
+loop do
+  if job = Job.find(:first, :conditions => ["state='pending' and start_at <= ?", Time.now], :order => "priority desc, start_at asc")
+    job.get_done!
+  else
+    RAILS_DEFAULT_LOGGER.info("BackgroundFu: Waiting for jobs...")
+    sleep 5
+  end
+  
+  Job.destroy_all(["state='finished' and updated_at < ?", 1.week.ago])
+end

data/generators/background/templates/background_ctl

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'daemons'
+require 'yaml'
+require 'erb'
+
+class Hash
+  def with_symbols!
+    self.keys.each{|key| self[key.to_s.to_sym] = self[key] }; self
+  end
+end
+
+options = YAML.load(
+  ERB.new(
+  IO.read(
+  File.dirname(__FILE__) + "/../../config/daemons.yml"
+  )).result).with_symbols!
+options[:dir_mode] = options[:dir_mode].to_sym
+
+Daemons.run File.dirname(__FILE__) + '/background.rb', options

data/generators/background/templates/daemons

@@ -0,0 +1,2 @@
+#!/usr/bin/env ruby
+Dir[File.dirname(__FILE__) + "/../lib/daemons/*_ctl"].each {|f| `nice ruby #{f} #{ARGV.first}`}

data/generators/background/templates/daemons.yml

@@ -0,0 +1,5 @@
+dir_mode: script
+dir: ../../log
+multiple: false
+backtrace: true
+monitor: true

data/generators/background/templates/example_monitored_worker.rb

@@ -0,0 +1,20 @@
+class ExampleMonitoredWorker
+  
+  # After including worker monitoring you can invoke record_progress() method.
+  include BackgroundFu::WorkerMonitoring
+  
+  def long_and_monitored
+    my_progress = 0
+    
+    record_progress(my_progress)
+
+    while(my_progress < 100)
+      my_progress += 1
+      record_progress(my_progress)
+      sleep 1
+    end
+    
+    record_progress(100)
+  end
+  
+end

data/generators/background/templates/migration.rb

@@ -0,0 +1,30 @@
+class CreateJobs < ActiveRecord::Migration
+  def self.up
+    create_table :jobs do |t|
+      t.string  :worker_class
+      t.string  :worker_method
+      
+      t.text    :args
+      t.integer :priority
+
+      t.integer :progress
+      t.string  :state
+      
+      t.integer :lock_version, :default => 0
+      
+      t.timestamp :start_at
+      t.timestamp :started_at
+      t.timestamps
+      
+      t.columns << 'result longtext' # text can store 65kb only, it's often too short
+    end
+
+    add_index :jobs, :state
+    add_index :jobs, :start_at
+    add_index :jobs, :priority
+  end
+
+  def self.down
+    drop_table :jobs
+  end
+end

data/generators/background/templates/scaffold/_job.html.erb

@@ -0,0 +1,39 @@
+<td class="checkbox">
+  <% case job.state
+    when "running" %>
+    <%= link_to_remote("Stop", :url => admin_job_path(job, :command => "stop"), :method => :put, :confirm => "Are you sure?") %>
+  <% when "failed", "stopped"  %>
+    <%= link_to_remote("Restart", :url => admin_job_path(job, :command => "restart"), :method => :put, :confirm => "Are you sure?") %> <br />
+    <%= link_to_remote("Delete", :url => admin_job_path(job), :method => :delete, :confirm => "Are you sure?") %>
+  <% when "finished", "pending" %>
+    <%= link_to_remote("Delete", :url => admin_job_path(job), :method => :delete, :confirm => "Are you sure?") %><br />
+    <%= link_to("Download result", formatted_admin_job_path(job, :txt)) if downloadable?(job) %>
+  <% end %>
+  <br />
+</td>
+<td class="progress">
+  <%= render :partial => "progress_indicator", 
+    :locals => {
+      :progress  => job.progress, 
+      :elapsed   => job.elapsed,
+      :estimated => job.estimated,
+      :state     => job.state
+    } 
+  %>
+</td>
+<td class="info">
+  <h2><%= job.worker_class %>.new.<%= job.worker_method %>( <strong><%= h truncate(job.args.map(&:inspect).join(", "), 255) %></strong> )</h2>
+  <p>
+    started at: <strong><%= time_ago_in_words_with_customization(job.started_at) %></strong>,
+    created at: <strong><%= time_ago_in_words_with_customization(job.created_at) %></strong>,
+    updated at: <strong><%= time_ago_in_words_with_customization(job.updated_at) %></strong>,<br />
+    state:      <strong><%= job.state %></strong>,
+    progress:   <strong><%= job.progress || "n/a" %></strong>,
+    result:     <strong><%=h truncate(job.result.inspect, 255) %></strong>
+  </p>
+</td>
+<script type="text/javascript">
+  //<![CDATA[
+    job_state_<%= dom_id(job) %> = "<%= job.state %>";
+  //]]>
+</script>

data/generators/background/templates/scaffold/_job_deleted.html.erb

@@ -0,0 +1,5 @@
+<script type="text/javascript">
+  //<![CDATA[
+    job_state_<%= dom_id(job_deleted) %> = "deleted";
+  //]]>
+</script>

data/generators/background/templates/scaffold/_progress_indicator.html.erb

@@ -0,0 +1,5 @@
+<div class="progress-indicator">
+  <span class="bar <%= state %>" style="width: <%= progress %>%;"></span>
+  <span class="label elapsed"><%= seconds_in_short(elapsed) if elapsed.to_i > 0 %></span>
+  <span class="label estimated"><%= seconds_in_short(estimated) if estimated.to_i > 0 %></span>
+</div>

data/generators/background/templates/scaffold/background_fu.css

@@ -0,0 +1,23 @@
+.progress-indicator { height: 6em; width: 30em; position: relative; border: 1px solid #536070; background-color: #A8B1BC; }
+.progress-indicator span { position: absolute; height: 100%;}
+.progress-indicator .bar.running  { background-color: #1687C2; }
+.progress-indicator .bar.finished { background-color: #00AF00; }
+.progress-indicator .bar.stopping { background-color: orange; }
+.progress-indicator .bar.stopped  { background-color: #E90000; }
+.progress-indicator .bar.failed   { background-color: #C90000; }
+
+.progress-indicator .label { width: 100%; font-size: 1.5em; line-height: 1.5em; font-weight: bold; font-family: "Myriad Pro", sans-serif; color: white; }
+.progress-indicator .elapsed { margin-left: 2%; }
+.progress-indicator .estimated { margin-left: 85%; }
+
+table.jobs td { border: none; vertical-align: top; color: #555; border-bottom: 1px solid white; }
+table.jobs tr.even td{ background-color: #f6f6f6; }
+table.jobs tr.odd td { background-color: #efefef; }
+table.jobs td h2 { margin-top: 0; }
+table.jobs strong { color: #000; font-weight: bold; }
+
+form.job input { margin: 0 0 1em 0; }
+form.job textarea { width: 50%; }
+form.job input.worker-class  { font-size: 2em; font-weight: bold; width: 33%; }
+form.job input.worker-method { font-size: 1.5em; font-weight: bold; width: 33%; }
+form.job input.button { font-size: 1.2em; font-weight: bold; }

data/generators/background/templates/scaffold/index.html.erb

@@ -0,0 +1,27 @@
+<div>
+  <% form_for(:job, :html => {:class => "job"}) do |f| %>
+    <%= f.label :worker_class %><br />
+    <%= f.text_field :worker_class, :class => "worker-class" %><br />
+    <%= f.label :worker_method %><br />
+    <%= f.text_field :worker_method, :class => "worker-method" %><br />
+    <%= f.label :args, "Args - each line (including empty) is interpreted as a string argument" %><br />
+    <%= f.text_area :args %><br />
+    <%= f.submit "Enqueue", :class => "button" %><br />
+  <% end %>
+</div>
+
+<hr style="visibility:hidden; margin: 20px auto" />
+
+<table class="jobs">
+  <% @jobs.each do |job| %>
+    <tr class="job <%= cycle(:odd, :even) %>" id="<%= dom_id(job) %>">
+    <%= render :partial => "job", :locals => {:job => job} %>
+    </tr>
+    <%= periodically_call_remote(
+      :url       => admin_job_path(job), 
+      :method    => "get", 
+      :interval  => 5, 
+      :condition => "/^(running|pending|stopping)$/.match(job_state_#{dom_id(job)})")
+    %>  
+  <% end %>
+</table>

data/generators/background/templates/scaffold/jobs.html.erb

@@ -0,0 +1,22 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Background Jobs - BackgroundFu</title>
+  <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.5.0/build/reset-fonts-grids/reset-fonts-grids.css"> 
+  <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.5.0/build/base/base-min.css"> 
+  <style type="text/css"> 
+    #custom-doc { width: 90%; min-width: 250px; } 
+  </style>
+  <%= javascript_include_tag :defaults %>
+  <%= stylesheet_link_tag 'background_fu' %>
+</head>
+<body>
+  <div id="custom-doc" class="yui-t7">
+    <div id="hd"><h1>BackgroundFu Jobs</h1></div> 
+    <div id="bd"><div class="yui-g"> 
+      <%= yield %>
+    </div></div> 
+    <div id="ft" style="text-align: center;"><a href="http://trix.pl/background_fu">BackgroundFu</a> Running Background Jobs Made Dead Simple <a href="http://trix.pl">Jacek Becela</a> 2008 </div> 
+  </div>
+</body>
+</html>

data/generators/background/templates/scaffold/jobs_controller.rb

@@ -0,0 +1,60 @@
+class Admin::JobsController < Admin::ApplicationController
+
+  def index
+    @jobs = Job.find(:all, :order => "id desc")
+  end
+
+  def show
+    @job = Job.find(params[:id])
+
+    respond_to do |format|
+      format.text do 
+        if @job.result.respond_to?(:join)
+          send_data @job.result.join("\n"), :type => "text/plain", :disposition => "attachment"
+        else
+          render :nothing => true, :status => 404
+        end
+      end
+      format.js do
+        render :update do |page|
+          page[@job].replace_html :partial => "job"
+        end
+      end
+    end
+  end
+  
+  def create
+    params[:job][:args] = params[:job][:args].split("\n").map(&:strip)
+    @job = Job.new(params[:job])
+    
+    if @job.save
+      redirect_to admin_jobs_path
+    else
+      render :action => "new"
+    end
+  end
+
+  def update
+    @job = Job.find(params[:id])
+    
+    if params[:command] == "stop"
+      @job.stop!
+    elsif params[:command] == "restart" 
+      @job.restart!
+    end
+
+    render :update do |page|
+      page[@job].replace_html :partial => "job"
+    end
+  end
+
+  def destroy
+    @job = Job.find(params[:id])
+    @job.destroy
+
+    render :update do |page|
+      page[@job].replace_html :partial => "job_deleted", :object => @job
+    end
+  end
+
+end

data/generators/background/templates/scaffold/jobs_helper.rb

@@ -0,0 +1,32 @@
+module Admin::JobsHelper
+
+  def seconds_in_short(seconds)
+    seconds = seconds.to_i
+    minutes = seconds / 60
+    hours   = seconds / (60 * 60)
+    days    = seconds / (60 * 60 * 24)
+
+    if days > 0
+      return "#{days} d"
+    elsif hours > 0
+      return "#{hours} h"
+    elsif minutes > 0
+      return "#{minutes} m"
+    else
+      return "#{seconds} s"
+    end
+  end
+  
+  def time_ago_in_words_with_customization(time)
+    if time
+      "#{time_ago_in_words(time)} ago"
+    else
+      "n/a"
+    end
+  end
+  
+  def downloadable?(job)
+    job.result.respond_to?(:join)
+  end
+
+end

data/init.rb

@@ -0,0 +1,5 @@
+Dependencies.load_paths << "#{RAILS_ROOT}/lib/workers"
+
+if ActiveRecord::Base.allow_concurrency
+  Job.send!(:include, Job::BonusFeatures)
+end

data/lib/background_fu/worker_monitoring.rb

@@ -0,0 +1,19 @@
+# Include it in your workers to enable progress monitoring and stopping jobs.
+module BackgroundFu::WorkerMonitoring
+    
+  # In most cases you will have some loop which will execute known (m) times.
+  # Every time the loop iterates you increment a counter (n).
+  # The formula to get progress in percents is: 100 * n / m.
+  # If you invoke this method with second argument, then this is calculated for you.
+  # You also can omit second argument and progress will be passed directly to db.
+  def record_progress(progress_or_iteration, iterations_count = nil)
+    if iterations_count.to_i > 0
+      @progress = ((progress_or_iteration.to_f / iterations_count) * 100).to_i
+    else
+      @progress = progress_or_iteration.to_i
+    end
+
+    throw(:stopping, true) if @stopping
+  end
+
+end

data/lib/background_fu.rb

@@ -0,0 +1,5 @@
+module BackgroundFu
+  
+  VERSION = "1.0.2"
+  
+end

data/lib/job/bonus_features.rb

@@ -0,0 +1,99 @@
+module Job::BonusFeatures
+  
+  def self.included(base)
+    base.states += %w(stopping stopped)
+    base.generate_state_helpers
+
+    base.alias_method_chain :invoke_worker, :threads
+    base.alias_method_chain :ensure_worker, :threads
+    base.alias_method_chain :restart!,      :threads
+  end
+  
+  def invoke_worker_with_threads
+    monitor_worker
+    
+    res = catch(:stopping) do
+      invoke_worker_without_threads; nil
+    end
+    
+    self.state = res ? "stopped" : "finished"
+  end
+
+  def ensure_worker_with_threads
+    ensure_worker_without_threads
+    cleanup_after_threads
+  end
+  
+  # The record_progress() method becomes available when your worker class includes
+  # Background::WorkerMonitoring.
+  #
+  # Every time worker invokes record_progress() is a possible stopping place.
+  #
+  # How it works:
+  # 1. invoke job.stop! to set a state (stopping) in a db
+  # 2. Monitoring thread picks up the state change from db
+  #    and sets @stopping to true in the worker.
+  # 3. The worker invokes a register_progress() somewhere during execution.
+  # 4. The record_progress() method throws :stopping symbol if @stopping == true
+  # 5. The job catches the :stopping symbol and reacts upon it.
+  # 6. The job is stopped in a merciful way. No one gets harmed.
+  def stop!
+    if running?
+      update_attribute(:state, "stopping")
+      logger.info("BackgroundFu: Stopping job. Job(id: #{id}).")
+    end
+  end
+  
+  # Overwritten because of new "stopped" state.
+  def restart_with_threads!
+    if stopped? || failed?
+      update_attributes!(
+        :result     => nil, 
+        :progress   => nil, 
+        :started_at => nil, 
+        :state      => "pending"
+      ) 
+      logger.info("BackgroundFu: Restarting job. Job(id: #{id}).")
+    end
+  end
+
+  # This is the only place where multi-threading 
+  # is used in the plugin and is completely optional.
+  def monitor_worker
+    Thread.new do
+      # 1. running? - check if not failed or finished.
+      # 2. !Job.find(id).stopping? - check if someone ordered stopping the job.  
+      while(running? && !Job.find(id).stopping?)
+        current_progress = @worker.instance_variable_get("@progress")
+
+        if current_progress == progress
+          sleep 5
+        else
+          update_attribute(:progress, current_progress)
+          sleep 1
+        end
+      end
+
+      # If someone ordered stopping a job we infrom the worker that it should stop.
+      if(Job.find(id).stopping?)
+        @worker.instance_variable_set("@stopping", true)
+      end
+    end
+    logger.info("BackgroundFu: Job monitoring started. Job(id: #{id}).")
+  end
+
+  # Closes database connections left after finished threads.
+  def cleanup_after_threads
+    ActiveRecord::Base.verify_active_connections!
+  end
+  
+  def elapsed
+    (updated_at.to_f - started_at.to_f).to_i if !pending?
+  end
+  
+  # seconds to go, based on estimated and progress
+  def estimated
+    ((elapsed * 100) / progress) - elapsed if running? && (1..99).include?(progress.to_i)
+  end
+
+end

data/lib/job.rb

@@ -0,0 +1,110 @@
+# Example:
+# 
+# job = Job.enqueue!(MyWorker, :my_method, "my_arg_1", "my_arg_2")
+class Job < ActiveRecord::Base
+
+  cattr_accessor :states
+  self.states = %w(pending running finished failed)
+
+  serialize :args, Array
+  serialize :result
+
+  before_create :setup_state, :setup_priority, :setup_start_at
+  validates_presence_of :worker_class, :worker_method
+  
+  attr_readonly :worker_class, :worker_method, :args
+  
+  def self.enqueue!(worker_class, worker_method, *args)
+    job = create!(
+      :worker_class  => worker_class.to_s,
+      :worker_method => worker_method.to_s,
+      :args          => args
+    )
+    logger.info("BackgroundFu: Job enqueued. Job(id: #{job.id}, worker: #{worker_class}, method: #{worker_method}, argc: #{args.size}).")
+  end
+
+  # Invoked by a background daemon.
+  def get_done!
+    initialize_worker
+    invoke_worker
+  rescue Exception => e
+    rescue_worker(e)
+  ensure
+    ensure_worker
+  end
+  
+  # Restart a failed job.
+  def restart!
+    if failed? 
+      update_attributes!(
+        :result     => nil, 
+        :progress   => nil, 
+        :started_at => nil, 
+        :state      => "pending"
+      )
+      logger.info("BackgroundFu: Job restarted. Job(id: #{id}).")
+    end
+  end
+  
+  def initialize_worker
+    update_attributes!(:started_at => Time.now, :state => "running")
+    @worker = worker_class.constantize.new
+    logger.info("BackgroundFu: Job initialized. Job(id: #{id}).")
+  end
+  
+  def invoke_worker
+    self.result = @worker.send!(worker_method, *args)
+    self.state  = "finished"
+    logger.info("BackgroundFu: Job finished. Job(id: #{id}).")
+  end
+  
+  def rescue_worker(exception)
+    self.result = [exception.message, exception.backtrace.join("\n")].join("\n\n")
+    self.state  = "failed"
+    logger.info("BackgroundFu: Job failed. Job(id: #{id}).")
+  end
+  
+  def ensure_worker
+    self.progress = @worker.instance_variable_get("@progress")
+    save!
+  rescue StaleObjectError
+    # Ignore this exception as its only purpose is
+    # not allowing multiple daemons execute the same job.
+    logger.info("BackgroundFu: Race condition handled (It's OK). Job(id: #{id}).")
+  end
+
+  def self.generate_state_helpers
+    states.each do |state_name|
+      define_method("#{state_name}?") do
+        state == state_name
+      end
+
+      # Job.running => array of running jobs, etc.
+      self.class.send!(:define_method, state_name) do
+        find_all_by_state(state_name, :order => "id desc")
+      end
+    end
+  end
+  generate_state_helpers
+
+  def setup_state
+    return unless state.blank?
+
+    self.state = "pending" 
+  end
+  
+  # Default priority is 0. Jobs will be executed in descending priority order (negative priorities allowed).
+  def setup_priority
+    return unless priority.blank?
+    
+    self.priority = 0
+  end
+  
+  # Job will be executed after this timestamp.
+  def setup_start_at
+    return unless start_at.blank?
+    
+    self.start_at = Time.now
+  end
+
+end  

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification 
+name: ncr-background_fu
+version: !ruby/object:Gem::Version 
+  version: 1.0.2
+platform: ruby
+authors: 
+- Jacek Becela
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-05-27 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: daemons
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.0.9
+    version: 
+description: Background tasks in Ruby On Rails made dead simple.
+email: 
+- jacek.becela@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- generators/background/USAGE
+- generators/background/background_generator.rb
+- generators/background/templates/background.rb
+- generators/background/templates/background_ctl
+- generators/background/templates/daemons
+- generators/background/templates/daemons.yml
+- generators/background/templates/example_monitored_worker.rb
+- generators/background/templates/example_worker.rb
+- generators/background/templates/migration.rb
+- generators/background/templates/scaffold/_job.html.erb
+- generators/background/templates/scaffold/_job_deleted.html.erb
+- generators/background/templates/scaffold/_progress_indicator.html.erb
+- generators/background/templates/scaffold/background_fu.css
+- generators/background/templates/scaffold/index.html.erb
+- generators/background/templates/scaffold/jobs.html.erb
+- generators/background/templates/scaffold/jobs_controller.rb
+- generators/background/templates/scaffold/jobs_helper.rb
+- init.rb
+- lib/background_fu.rb
+- lib/background_fu/worker_monitoring.rb
+- lib/job.rb
+- lib/job/bonus_features.rb
+has_rdoc: false
+homepage: http://github.com/ncr/background-fu
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: background-fu
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: Background tasks in Ruby On Rails made dead simple.
+test_files: []
+