# \[ANN\] bj-0.0.3 **URL:** \ **Category:** Rails\ **Created:** [December 22, 2007, 5:46pm UTC](https://www.ruby-forum.com/t/ann-bj-0-0-3/123956 "2007-12-22T17:46:06Z")\ **Posts on this page:** 1\ **Page:** 1
**Author:** ![ara.t.howard](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/a/a8b319/32.png) [@ara.t.howard](https://www.ruby-forum.com/u/ara.t.howard)\ **Post date:** [December 22, 2007, 5:46pm UTC](https://www.ruby-forum.com/t/ann-bj-0-0-3/123956/1 "2007-12-22T17:46:06Z")
NAME bj SYNOPSIS bj (migration\_code|generate\_migration|migrate|setup|plugin|run| submit|list|set|config|pid) [options]+ DESCRIPTION * * * ## Overview ``` Backgroundjob (Bj) is a simple to use background priority queue ``` for rails. Although not yet tested on windows, the design of bj is such that operation should be possible on any operating system, including M$. ``` Jobs can be submitted to the queue directly using the api or from ``` the commandline using the ‘bj’ script. For example ``` code: Bj.submit 'cat /etc/password' cli: bj submit cat /etc/password When used from inside a rails application bj arranges that another ``` process will always be running in the background to process the jobs that you submit. By using a separate process to run jobs bj does not impact the resource utilization of your rails application at all and enables several very cool features: ``` 1) Bj allows you to sumbit jobs to any of your configured ``` databases and, in each case, spawns a separate background process to run jobs from that queue ``` Bj.in :production do Bj.submit 'production_job.exe' end Bj.in :development do Bj.submit 'development_job.exe' end 2) Although bj ensures that a process is always running to ``` process your jobs, you can start a proces manually. This means that any machine capable of seeing your RAILS\_ROOT can run jobs for your application, allowing one to setup a cluster of machines doing the work of a single front end rails applicaiton. * * * ## Install ``` Bj can be installed two ways: as a gem or as a plugin. gem: 1) $sudo gem install bj 2) add "require 'bj'" to config/environment.rb 3) bj setup plugin: 1) ./script/plugin install ``` [http://codeforpeople.rubyforge.org/svn/rails/plugins/bj](http://codeforpeople.rubyforge.org/svn/rails/plugins/bj) 2) ./script/bj setup * * * ## Api ``` submit jobs for background processing. 'jobs' can be a string or ``` array of strings. options are applied to each job in the ‘jobs’, and the list of submitted jobs is always returned. options (string or symbol) can be ``` :rails_env => production|development|key_in_database_yml when given this keyword causes bj to submit jobs ``` to the specified database. default is RAILS\_ENV. ``` :priority => any number, including negative ones. default is ``` zero. ``` :tag => a tag added to the job. simply makes searching easier. :env => a hash specifying any additional environment vars the ``` background process should have. ``` :stdin => any stdin the background process should have. eg: jobs = Bj.submit 'echo foobar', :tag => 'simple job' jobs = Bj.submit '/bin/cat', :stdin => 'in the hat', :priority ``` =\> 42 ``` jobs = Bj.submit './script/runner ./scripts/a.rb', :rails_env => ``` ‘production’ ``` jobs = Bj.submit './script/runner /dev/stdin', :stdin => 'p RAILS_ENV', :tag => 'dynamic ruby code' jobs Bj.submit array_of_commands, :priority => 451 ``` when jobs are run, they are run in RAILS\_ROOT. various attributes are available _only_ once the job has finished. you can check whether or not a job is finished by using the #finished method, which simple does a reload and checks to see if the exit\_status is non-nil. ``` eg: jobs = Bj.submit list_of_jobs, :tag => 'important' ... jobs.each do |job| if job.finished? p job.exit_status p job.stdout p job.stderr end end ``` See lib/bj/api.rb for more details. * * * ## Sponsors ``` http://www.engineyard.com/ http://quintess.com/ http://eparklabs.com/ ``` PARAMETERS –rails\_root=rails\_root, -R (0 ~\> rails\_root=) the rails\_root will be guessed unless you set this –rails\_env=rails\_env, -E (0 ~\> rails\_env=development) set the rails\_env –log=log, -l (0 ~\> log=STDERR) set the logfile –help, -h AUTHOR removed\_email\_address@domain.invalid URIS [http://codeforpeople.com/lib/ruby/](http://codeforpeople.com/lib/ruby/) [http://rubyforge.org/projects/codeforpeople/](http://rubyforge.org/projects/codeforpeople/) [http://codeforpeople.rubyforge.org/svn/rails/plugins/](http://codeforpeople.rubyforge.org/svn/rails/plugins/) HISTORY 0.0.3: - _many_ small bug fixes - plugin install should now pick up dependancies from plugin dir, last release had LOAD\_PATH/gem issues and was picking up globally installed gems - automatic management of the background processing can be turned off if you want to manage your own processes - all jobs are automatically restartable unless submitted with :restartable =\> false this means that, should a runner ever die, upon restart any jobs that were mid-process will automatically be restarted - signal based parent lifeline move out of thread and into even loop - :lock =\> true added to a few AR finds to support true write serializable transaction isolation when the db supports it - all migrations now use :force =\> true and - running ‘bj setup’ will always generate a new migration, even if you’ve already run it before. this allows easy version upgrades. - a few command would blow up on windows because they weren’t prefixed with ‘ruby’. gotta love the lack of #shebang line on windoze… - ./script/bj is searched first before system path env var - a default PATH is provided for whacky systems without one - database.yml is filtered through ERB ala rails FUTURE - windows version around the corner - time to live on running jobs THANKS - testing/feedback by steve steve midgley - testing/feedback by andrew stewart - testing/feedback by dave ringoen - testing/feedback by ezra zygmuntowicz enjoy bj.