h1. kthxbye

Kthxbye is the answer to a fairly unique-yet-common problem: Background job 
processing when we care about the result.

There are a number of projects I can think of where a job that takes longer than
a user ought to be waiting for a result (due to server timeout length or out of 
simple app responsiveness courtesy to the user) and yet I need the result of the
operation to be returned to the user.

Here's a real-world example. I work with a set of legacy Oracle databases that
stores much of our business logic as PLSQL procedures. Yes, this is not "The
Rails Way™" but it's the only way for the company I work for right now.
Many of the procedures that I run as part of several of the applications I 
support can take on average one minute or more with a standard deviation of
almost 2 minutes (with a forced timeout of 5 minutes). That's kinda a long time
to sit and wait on a web app. 

<img src="http://img.skitch.com/20100901-gadna641fj4wdeswgj74y2pssq.png" alt="RLA - IWP Analysis"/>

We don't really want users sitting waiting for up to 5 minutes (when it forces 
failure) unable to do anything or (even worse) hitting refresh or the action
again. Especially bad when this can mean the HTTP server is getting backed up
as more and more people run these long running processes.

Moreover, the users need to get response from the completed job before moving
on. Most job processors (DJ, Resque) are setup for running jobs that do not
require the result to be returned to the web app (think mass-mailers, queue
population, image resizing). They just run and the output goes to a database,
an inbox or a file server.

h2. Enter Kthxbye

Kthxbye is an attempt to solve this problem. It is based heavily off of 
"Resque":http://github.com/defunkt/resque and why not an addition to Resque?
I needed some hack time with Redis on my own as I've never used it before...

bq. I can learn any language or tool in a matter of days if you give me 
  1. a good manual
  2. an even better project to work on.

_- Prof. Shumacher_

This project accomplishes both those goals. This is an attempt to learn 
something, using Resque and Redis docs as a manual, while at the same time 
creating a much needed solution to a problem.

The idea is to be able to do the following:

    # dummy job class
    class MyJob
      def self.perform(data)
        puts "Do something with #{data}"
        data.gsub(/hello/i, "Goodbye")
      end
    end

    # setup options, then connect
    Kthxbye::Config.setup(:redis_server => 'localhost', :redis_port => 8080)
    
    # each enqueued job returns a unique id to poll with
    unique_id = Kthxbye.enqueue("jobs", MyJob, "Hello World")

    # ... code code code ...

    # polls queue every 5 seconds
    computed_value = Kthxbye.poll("jobs", unique_id, 5)

and then in some other world, on some other machine, (that still has knowledge of MyJob)

    # inits with queue
    worker = Kthxbye::Worker.new("jobs")

    # connects to queue and runs jobs found there
    worker.run

Pretty... damn... simple.

h2. Note on Patches/Pull Requests
 
* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a
  future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.

h2. Copyright

Copyright (c) 2010 Luke van der Hoeven. See LICENSE for details.