diff --git a/README.md b/README.md index 94bdbf4b..0f00e2a9 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,43 @@ queue provider. +# Putting jobs on queues + +Some terminology before we get started: + +* *Queues* are queues, in the computer science way. Technically, they are + Redis lists where work is `lpush`'ed on and `rpop`'ed from. +* *Jobs* are a definitions of work that can be carried out by a different + process. Technically, they are just plain old Python function calls, with + arguments and return values and the like. +* *Workers* are Python processes that pop off work from queues and start + executing them. They report back any return values or exceptions. + +To put work on queues, tag a Python function call as a job, like so: + + @job('default') + def slow_fib(n): + if n <= 1: + return 1 + else: + return slow_fib(n-1) + slow_fib(n-2) + +You can still call the function synchronously: + + from fib import slow_fib + slow_fib(4) + +You can find an example implementation in the `examples/` directory. To run +it, open three terminal windows and run the following commands in them: + +1. `python example/run_worker.py` +1. `python example/run_worker.py` +1. `python example/run_example.py` + +This starts two workers and starts crunching the fibonacci calculations in the +background, while the script shows the crunched data updates every second. + + ### Installation Simply use the following command to install the latest released version: diff --git a/examples/fib.py b/examples/fib.py new file mode 100644 index 00000000..521e06d2 --- /dev/null +++ b/examples/fib.py @@ -0,0 +1,8 @@ +from rq import job + +@job('default') +def slow_fib(n): + if n <= 1: + return 1 + else: + return slow_fib(n-1) + slow_fib(n-2) diff --git a/examples/run_example.py b/examples/run_example.py new file mode 100644 index 00000000..00ab3919 --- /dev/null +++ b/examples/run_example.py @@ -0,0 +1,37 @@ +import os +import time +from rq import push_connection +from redis import Redis +from fib import slow_fib + +push_connection(Redis()) + +sync = False +if sync: + print 'Synchronously:' + for x in range(22, 33): + print 'fib(%d) = %d' % (x, slow_fib(x)) + print 'Done' +else: + # Kick off the tasks asynchronously + async_results = {} + for x in range(22, 33): + async_results[x] = slow_fib.delay(x) + + done = False + while not done: + os.system('clear') + print 'Asynchronously: (now = %s)' % time.time() + done = True + for x in range(22, 33): + result = async_results[x].return_value + if result is None: + done = False + result = '(calculating)' + print 'fib(%d) = %s' % (x, result) + print '' + print 'To start the actual in the background, run a worker:' + print ' python examples/run_worker.py' + time.sleep(1) + + print 'Done' diff --git a/examples/run_worker.py b/examples/run_worker.py new file mode 100644 index 00000000..6be28b91 --- /dev/null +++ b/examples/run_worker.py @@ -0,0 +1,7 @@ +from redis import Redis +from rq import push_connection +from rq.daemon import run_daemon + +push_connection(Redis()) + +run_daemon(['default'])