genki-background_fu 1.0.8.2

data/History.txt

@@ -0,0 +1,49 @@
+=== 1.0.8.1 / 2008-09-7
+
+* Suppress the warning on Rails-2.1.1.
+
+=== Master / 2008-07-31
+
+* Make it clear that generated views are meant to be used when bonus features are enabled. [Trevor Turk, ncr]
+
+=== 1.0.8 / 2008-07-30
+
+* Reverted back to "text" column for storing job results so it works on PostgreSQL. [Trevor Turk, ncr]
+
+=== 1.0.7 / 2008-07-16
+
+* Updated docs and fixed a bug regarding started_at and Time.now.utc (the lack of #utc in some places resulted in jobs not starting). [Jeff Berg, ncr]
+* Fixed and refactored scaffolding. [ncr]
+* Removed deprecated Dependencies usage. [ncr]
+* Updated links in footer. [ncr]
+
+=== 1.0.6 / 2008-07-03
+
+* Updated docs to mention config/routes.rb. [Joe Goldwasser, ncr]
+
+=== 1.0.5 / 2008-06-02
+
+* Fixed enqueue method (now properly returns enqueued job). [Jake Yoon, ncr]
+* Fixed background.rb generator so it doens't blow up if Bonus Features are disabled. [Jake Yoon, ncr]
+
+=== 1.0.4 / 2008-05-28
+
+* GitHub is now generating a gem. [ncr]
+* Making sure that it will work as a plugin when installed as a gem. [ncr]
+
+=== 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,30 @@
+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/_form.html.erb
+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/application_controller.rb
+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
+generators/background/templates/scaffold/new.html.erb
+lib/background_fu.rb
+lib/background_fu/worker_monitoring.rb
+lib/job.rb
+lib/job/bonus_features.rb
+rails/init.rb

data/README.txt

@@ -0,0 +1,176 @@
+= 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 (to be used with concurrency enabled).
+* 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
+  
+  If you want to use default generated views, update your config/routes.rb:
+  
+  map.namespace "admin" do |admin|
+    admin.resources :jobs
+  end
+  
+  Then you can point your browser to http://localhost:3000/admin/jobs
+
+== 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
+config.active_record.allow_concurrency = true
+in your environment.
+
+These features are: 
+ * monitoring progress (perfect for ajax progress bars)
+ * stopping a running worker in a merciful way.
+ 
+Generated admin views are meant to be used only when bonus features (concurrency) are enabled.
+
+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/background-fu.gemspec

@@ -0,0 +1,23 @@
+Gem::Specification.new do |s|
+  s.name = %q{background_fu}
+  s.version = "1.0.8.2"
+
+  s.specification_version = 2 if s.respond_to? :specification_version=
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jacek Becela"]
+  s.date = %q{2008-05-28}
+  s.description = %q{Background tasks in Ruby On Rails made dead simple.}
+  s.email = ["jacek.becela@gmail.com"]
+  s.extra_rdoc_files = ["History.txt", "Manifest.txt", "README.txt"]
+  s.files = ["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", "lib/background_fu.rb", "lib/background_fu/worker_monitoring.rb", "lib/job.rb", "lib/job/bonus_features.rb", "rails/init.rb"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/ncr/background-fu}
+  s.rdoc_options = ["--main", "README.txt"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{background-fu}
+  s.rubygems_version = %q{1.1.1}
+  s.summary = %q{Background tasks in Ruby On Rails made dead simple.}
+
+  s.add_dependency(%q<daemons>, [">= 1.0.10"])
+end

data/generators/background/USAGE

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

data/generators/background/background_generator.rb

@@ -0,0 +1,61 @@
+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/application_controller.rb', 'app/controllers/admin/application_controller.rb'
+        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/new.html.erb',                 'app/views/admin/jobs/new.html.erb'
+        m.file 'scaffold/_form.html.erb',               'app/views/admin/jobs/_form.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.utc], :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/example_worker.rb

@@ -0,0 +1,8 @@
+# Simple, non-monitored worker.
+class ExampleWorker
+  
+  def add(a, b)
+    a + b
+  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.text    :result
+
+      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
+    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,19 @@
+<div>
+  <%= render :partial => "form", :locals => { :job => @job } %>
+</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://github.com/ncr/background-fu/">BackgroundFu</a> Running Background Jobs Made Dead Simple <a href="http://en.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/lib/background_fu.rb

@@ -0,0 +1,5 @@
+module BackgroundFu
+  
+  VERSION = "1.0.8"
+  
+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/job.rb

@@ -0,0 +1,113 @@
+# 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}).")
+    
+    job
+  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.utc, :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.utc
+  end
+
+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/rails/init.rb

@@ -0,0 +1,11 @@
+require 'background_fu'
+require 'background_fu/worker_monitoring'
+require 'job'
+require 'job/bonus_features'
+
+# ActiveSupport::Dependencies will be here after edge becomes stable.
+ActiveSupport::Dependencies.load_paths << "#{RAILS_ROOT}/lib/workers"
+
+if ActiveRecord::Base.allow_concurrency
+  Job.send!(:include, Job::BonusFeatures)
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: genki-background_fu
+version: !ruby/object:Gem::Version 
+  version: 1.0.8.2
+platform: ruby
+authors: 
+- Jacek Becela
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-05-28 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.10
+    version: 
+description: Background tasks in Ruby On Rails made dead simple.
+email: 
+- jacek.becela@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- 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
+- lib/background_fu.rb
+- lib/background_fu/worker_monitoring.rb
+- lib/job.rb
+- lib/job/bonus_features.rb
+- rails/init.rb
+has_rdoc: true
+homepage: http://github.com/ncr/background-fu
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+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.2.0
+signing_key: 
+specification_version: 2
+summary: Background tasks in Ruby On Rails made dead simple.
+test_files: []
+