diff --git a/docs/examples/lib/BackgroundJobs.ipynb b/docs/examples/lib/BackgroundJobs.ipynb
new file mode 100644
index 0000000..3814164
--- /dev/null
+++ b/docs/examples/lib/BackgroundJobs.ipynb
@@ -0,0 +1,171 @@
+{
+ "worksheets": [
+ {
+ "cells": [
+ {
+ "source": "# Simple interactive bacgkround jobs with IPython\n\nWe start by loading the `backgroundjobs` library and defining a few trivial functions to illustrate things with.",
+ "cell_type": "markdown"
+ },
+ {
+ "cell_type": "code",
+ "language": "python",
+ "outputs": [],
+ "collapsed": false,
+ "prompt_number": 15,
+ "input": "from IPython.lib import backgroundjobs as bg\n\nimport sys\nimport time\n\ndef sleepfunc(interval=2, *a, **kw):\n args = dict(interval=interval,\n args=a,\n kwargs=kw)\n time.sleep(interval)\n return args\n\ndef diefunc(interval=2, *a, **kw):\n time.sleep(interval)\n raise Exception(\"Dead job with interval %s\" % interval)\n\ndef printfunc(interval=1, reps=5):\n for n in range(reps):\n time.sleep(interval)\n print 'In the background...', n\n sys.stdout.flush()\n print 'All done!'\n sys.stdout.flush()"
+ },
+ {
+ "source": "Now, we can create a job manager (called simply `jobs`) and use it to submit new jobs.\n
\nRun the cell below and wait a few seconds for the whole thing to finish, until you see the \"All done!\" printout.",
+ "cell_type": "markdown"
+ },
+ {
+ "cell_type": "code",
+ "language": "python",
+ "outputs": [
+ {
+ "output_type": "stream",
+ "stream": "stdout",
+ "text": "Starting job # 0 in a separate thread.\nStarting job # 2 in a separate thread.\nStarting job # 3 in a separate thread.\nStarting job # 4 in a separate thread.\nStarting job # 5 in a separate thread.\n"
+ },
+ {
+ "output_type": "stream",
+ "stream": "stdout",
+ "text": "In the background... 0\n"
+ },
+ {
+ "output_type": "stream",
+ "stream": "stdout",
+ "text": "In the background... 1\n"
+ },
+ {
+ "output_type": "stream",
+ "stream": "stdout",
+ "text": "In the background... 2\n"
+ },
+ {
+ "output_type": "stream",
+ "stream": "stdout",
+ "text": "All done!\n"
+ }
+ ],
+ "collapsed": false,
+ "prompt_number": 28,
+ "input": "jobs = bg.BackgroundJobManager()\n\n# Start a few jobs, the first one will have ID # 0\njobs.new(sleepfunc, 4)\njobs.new(sleepfunc, kw={'reps':2})\njobs.new('printfunc(1,3)')\n\n# This makes a couple of jobs which will die. Let's keep a reference to\n# them for easier traceback reporting later\ndiejob1 = jobs.new(diefunc, 1)\ndiejob2 = jobs.new(diefunc, 2)"
+ },
+ {
+ "source": "You can check the status of your jobs at any time:",
+ "cell_type": "markdown"
+ },
+ {
+ "cell_type": "code",
+ "language": "python",
+ "outputs": [
+ {
+ "output_type": "stream",
+ "stream": "stdout",
+ "text": "Completed jobs:\n0 : <function sleepfunc at 0x30c8500>\n2 : <function sleepfunc at 0x30c8500>\n3 : printfunc(1,3)\n\nDead jobs:\n4 : <function diefunc at 0x30df758>\n5 : <function diefunc at 0x30df758>\n\n"
+ }
+ ],
+ "collapsed": false,
+ "prompt_number": 29,
+ "input": "jobs.status()"
+ },
+ {
+ "source": "For any completed job, you can get its result easily:",
+ "cell_type": "markdown"
+ },
+ {
+ "cell_type": "code",
+ "language": "python",
+ "outputs": [
+ {
+ "output_type": "pyout",
+ "prompt_number": 31,
+ "text": "{'args': (), 'interval': 4, 'kwargs': {}}"
+ }
+ ],
+ "collapsed": false,
+ "prompt_number": 31,
+ "input": "jobs[0].result"
+ },
+ {
+ "source": "You can get the traceback of any dead job. Run the line\nbelow again interactively until it prints a traceback (check the status\nof the job):\n",
+ "cell_type": "markdown"
+ },
+ {
+ "cell_type": "code",
+ "language": "python",
+ "outputs": [
+ {
+ "output_type": "stream",
+ "stream": "stdout",
+ "text": "Status of diejob1: Dead (Exception), call jobs.traceback() for details\n---------------------------------------------------------------------------\nException Traceback (most recent call last)\n/home/fperez/usr/lib/python2.6/site-packages/IPython/lib/backgroundjobs.py in call(self)\n 462 \n 463 def call(self):\n--> 464 return self.func(*self.args, **self.kwargs)\n\n/home/fperez/ipython/ipython/docs/examples/lib/<ipython-input-15-54795a097787> in diefunc(interval, *a, **kw)\n 14 def diefunc(interval=2, *a, **kw):\n 15 time.sleep(interval)\n---> 16 raise Exception("Dead job with interval %s" % interval)\n 17 \n 18 def printfunc(interval=1, reps=5):\n\nException: Dead job with interval 1\n"
+ }
+ ],
+ "collapsed": false,
+ "prompt_number": 34,
+ "input": "print \"Status of diejob1:\", diejob1.status\ndiejob1.traceback() # jobs.traceback(4) would also work here, with the job number"
+ },
+ {
+ "source": "This will print all tracebacks for all dead jobs:",
+ "cell_type": "markdown"
+ },
+ {
+ "cell_type": "code",
+ "language": "python",
+ "outputs": [
+ {
+ "output_type": "stream",
+ "stream": "stdout",
+ "text": "Traceback for: <BackgroundJob #4: <function diefunc at 0x30df758>>\n---------------------------------------------------------------------------\nException Traceback (most recent call last)\n/home/fperez/usr/lib/python2.6/site-packages/IPython/lib/backgroundjobs.py in call(self)\n 462 \n 463 def call(self):\n--> 464 return self.func(*self.args, **self.kwargs)\n\n/home/fperez/ipython/ipython/docs/examples/lib/<ipython-input-15-54795a097787> in diefunc(interval, *a, **kw)\n 14 def diefunc(interval=2, *a, **kw):\n 15 time.sleep(interval)\n---> 16 raise Exception("Dead job with interval %s" % interval)\n 17 \n 18 def printfunc(interval=1, reps=5):\n\nException: Dead job with interval 1\n\nTraceback for: <BackgroundJob #5: <function diefunc at 0x30df758>>\n---------------------------------------------------------------------------\nException Traceback (most recent call last)\n/home/fperez/usr/lib/python2.6/site-packages/IPython/lib/backgroundjobs.py in call(self)\n 462 \n 463 def call(self):\n--> 464 return self.func(*self.args, **self.kwargs)\n\n/home/fperez/ipython/ipython/docs/examples/lib/<ipython-input-15-54795a097787> in diefunc(interval, *a, **kw)\n 14 def diefunc(interval=2, *a, **kw):\n 15 time.sleep(interval)\n---> 16 raise Exception("Dead job with interval %s" % interval)\n 17 \n 18 def printfunc(interval=1, reps=5):\n\nException: Dead job with interval 2\n\n"
+ }
+ ],
+ "collapsed": false,
+ "prompt_number": 33,
+ "input": "jobs.traceback()"
+ },
+ {
+ "source": "The job manager can be flushed of all completed jobs at any time:",
+ "cell_type": "markdown"
+ },
+ {
+ "cell_type": "code",
+ "language": "python",
+ "outputs": [
+ {
+ "output_type": "stream",
+ "stream": "stdout",
+ "text": "No jobs to flush.\n"
+ }
+ ],
+ "collapsed": false,
+ "prompt_number": 25,
+ "input": "jobs.flush()"
+ },
+ {
+ "source": "After that, the status is simply empty:",
+ "cell_type": "markdown"
+ },
+ {
+ "cell_type": "code",
+ "language": "python",
+ "outputs": [],
+ "collapsed": true,
+ "prompt_number": 27,
+ "input": "jobs.status()"
+ },
+ {
+ "input": "",
+ "cell_type": "code",
+ "collapsed": true,
+ "language": "python",
+ "outputs": []
+ }
+ ]
+ }
+ ],
+ "metadata": {
+ "name": "BackgroundJobs"
+ },
+ "nbformat": 2
+}
\ No newline at end of file