From 9b51083fd2d9cf330447e5370dd2eba5f96925e4 Mon Sep 17 00:00:00 2001
From: Vincent Driessen <vincent@3rdcloud.com>
Date: Mon, 14 Nov 2011 15:15:05 +0100
Subject: [PATCH] Add example and README updates.

---
 README.md               | 37 +++++++++++++++++++++++++++++++++++++
 examples/fib.py         |  8 ++++++++
 examples/run_example.py | 37 +++++++++++++++++++++++++++++++++++++
 examples/run_worker.py  |  7 +++++++
 4 files changed, 89 insertions(+)
 create mode 100644 examples/fib.py
 create mode 100644 examples/run_example.py
 create mode 100644 examples/run_worker.py

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'])