So I recently spent several days upgrading an outdated backgroundrb install to the latest version.  The Backgroundrb documentation is a bit sparse, so needless to say, I quickly became an active member of the mailing list.

Actually, to be honest, I didn't end up joining the mailing list until after I spent nearly an entire day pulling my hair out over a very strange bug.

Basically, I would create a new worker, send it some work to do, and then nothing would happen.  The code looked something like this:

key = MiddleMan.new_worker(:worker => :prince_xml_worker, :worker_key => worker_key)
worker = MiddleMan.worker(:prince_xml_worker, key)
worker.async_build_pdf(:arg => html_string) 

(I was working on pdf generation in case you couldn't tell)

A little tailing of the background_debug log told me that I was requesting work on an invalid worker.  An invalid worker?  How could it not be valid?  I just created the freakin thing.  I thought maybe the key was wrong or something, so I added a debugger after the 'new_worker' line and tested it out.  To my frustration, the generated key was perfectly valid, as was the worker retrieved from the middleman.

WTF?

I even managed to call the async worker method from the console and it worked perfectly.  But anytime that I would remove the debugger and let it run its course, nothing would happen.  It seemed ridiculous at first, but I thought maybe it just needs a second before its ready.  Nah...  That couldn't be it.  Just for kicks I put in a half-second sleep call where the debugger was previously, like so:

key = MiddleMan.new_worker(:worker => :prince_xml_worker, :worker_key => worker_key)
worker = MiddleMan.worker(:prince_xml_worker, key)
sleep(0.5)
worker.async_build_pdf(:arg => html_string) 

...and it worker perfectly.  

This just seemed crazy, so I got on the mailing list, described my problem and had a response within the hour.  I couldn't believe it, but i was right.  It said that if you're developing on OSX that backgroundrb basically needs a split second to start up the worker, before it can be used.  Since only our development environments were OSX, I conditionally enabled the sleep command based on the RAILS_ENV.  Unfortunately, our staging server, which is a Gentoo machine had the same problem, so I had to update the code accordinly.

ALSO...

Whatever you do, don't put 'puts' statements in your workers.  I ran into the situation where my debugging of code was actually causing it to break, which wasted more time than I'd care to admit.