Backgroundjob (Bj) is a brain dead simple zero admin background priority queue for Rails. Bj is robust, platform independent (including windows), and supports internal or external manangement of the background runner process.

Jobs can be submitted to the queue directly using the api or from the command line using the ./script/bj:

  api:
    Bj.submit 'cat /etc/password'

  command line:
    bj submit cat /etc/password

Bj’s priority queue lives in the database and is therefore durable - your jobs will live across an app crash or machine reboot. The job management is comprehensive capturing stdout, stderr, exit_status, and temporal statistics about each job:

  jobs = Bj.submit array_of_commands, :priority => 42

  ...

  jobs.each do |job|
    if job.finished?
      p job.stdout
      p job.stderr
      p job.exit_status
      p job.started_at
      p job.finished_at
    end
  end

In addition the background runner process logs all commands run and their exit_status to a log named using the following convention:

  rails_root/log/bj.#{ HOSTNAME }.#{ RAILS_ENV }.log

Bj allows you to submit jobs to multiple databases; for instance, if your application is running in development mode you may do:

  Bj.in :production do
    Bj.submit 'my_job.exe'
  end

Bj manages the ever growing list of jobs ran by automatically archiving them into another table (by default jobs > 24 hrs old are archived) to prevent the jobs table from becoming bloated and huge.

All Bj’s tables are namespaced and accessible via the Bj module:

  Bj.table.job.find(:all)         # jobs table
  Bj.table.job_archive.find(:all) # archived jobs
  Bj.table.config.find(:all)      # configuration and runner state

Bj always arranges for submitted jobs to run with a current working directory of RAILS_ROOT and with the correct RAILS_ENV setting. For example, if you submit a job in production it will have ENV[‘RAILS_ENV’] == ‘production’.

When Bj manages the background runner it will never outlive the rails application - it is started and stopped on demand as the rails app is started and stopped. This is also true for ./script/console - Bj will automatically fire off the background runner to process jobs submitted using the console.

Bj ensures that only one background process is running for your application - firing up three mongrels or fcgi processes will result in only one background runner being started. Note that the number of background runners does not determine throughput - that is determined primarily by the nature of the jobs themselves and how much work they perform per process.