1 files changed, 72 insertions, 0 deletions
diff --git a/src/mailman/queue/docs/runner.txt b/src/mailman/queue/docs/runner.txt
new file mode 100644
index 000000000..d24a8334c
--- /dev/null
+++ b/src/mailman/queue/docs/runner.txt
@@ -0,0 +1,72 @@
+Queue runners
+=============
+
+The queue runners (qrunner) are the processes that move messages around the
+Mailman system.  Each qrunner is responsible for a slice of the hash space in
+a queue directory.  It processes all the files in its slice, sleeps a little
+while, then wakes up and runs through its queue files again.
+
+
+Basic architecture
+------------------
+
+The basic architecture of qrunner is implemented in the base class that all
+runners inherit from.  This base class implements a .run() method that runs
+continuously in a loop until the .stop() method is called.
+
+    >>> mlist = config.db.list_manager.create(u'_xtest@example.com')
+    >>> mlist.preferred_language = u'en'
+
+Here is a very simple derived qrunner class.  Queue runners use a
+configuration section in the configuration files to determine run
+characteristics, such as the queue directory to use.  Here we push a
+configuration section for the test runner.
+
+    >>> config.push('test-runner', """
+    ... [qrunner.test]
+    ... max_restarts: 1
+    ... """)
+
+    >>> from mailman.queue import Runner
+    >>> class TestableRunner(Runner):
+    ...     def _dispose(self, mlist, msg, msgdata):
+    ...         self.msg = msg
+    ...         self.msgdata = msgdata
+    ...         return False
+    ...
+    ...     def _do_periodic(self):
+    ...         self.stop()
+    ...
+    ...     def _snooze(self, filecnt):
+    ...         return
+
+    >>> runner = TestableRunner('test')
+
+This qrunner doesn't do much except run once, storing the message and metadata
+on instance variables.
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ... To: _xtest@example.com
+    ...
+    ... A test message.
+    ... """)
+    >>> switchboard = config.switchboards['test']
+    >>> filebase = switchboard.enqueue(msg, listname=mlist.fqdn_listname,
+    ...                                foo='yes', bar='no')
+    >>> runner.run()
+    >>> print runner.msg.as_string()
+    From: aperson@example.com
+    To: _xtest@example.com
+    <BLANKLINE>
+    A test message.
+    <BLANKLINE>
+    >>> dump_msgdata(runner.msgdata)
+    _parsemsg: False
+    bar      : no
+    foo      : yes
+    lang     : en
+    listname : _xtest@example.com
+    version  : 3
+
+XXX More of the Runner API should be tested.