1 files changed, 70 insertions, 0 deletions
diff --git a/mailman/queue/docs/runner.txt b/mailman/queue/docs/runner.txt
new file mode 100644
index 000000000..e95e20ecd
--- /dev/null
+++ b/mailman/queue/docs/runner.txt
@@ -0,0 +1,70 @@
+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.
+
+    >>> import os
+    >>> from mailman.queue import Runner, Switchboard
+    >>> from mailman.configuration import config
+    >>> mlist = config.db.list_manager.create(u'_xtest@example.com')
+    >>> mlist.preferred_language = u'en'
+
+Here is a very simple derived qrunner class.  The class attribute QDIR tells
+the qrunner which queue directory it is responsible for.  Derived classes
+should also implement various methods to provide the special functionality.
+This is about as simple as a qrunner can be.
+
+    >>> queue_directory = os.path.join(config.QUEUE_DIR, 'test')
+    >>> class TestableRunner(Runner):
+    ...     QDIR = queue_directory
+    ...
+    ...     def _dispose(self, mlist, msg, msgdata):
+    ...         self.msg = msg
+    ...         self.msgdata = msgdata
+    ...         return False
+    ...
+    ...     def _doperiodic(self):
+    ...         self.stop()
+    ...
+    ...     def _snooze(self, filecnt):
+    ...         return
+
+    >>> runner = TestableRunner()
+    >>> switchboard = Switchboard(queue_directory)
+
+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.
+    ... """)
+    >>> 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>
+    >>> sorted(runner.msgdata.items())
+    [('_parsemsg', False),
+     ('bar', 'no'), ('foo', 'yes'),
+     ('lang', u'en'), ('listname', u'_xtest@example.com'),
+     ('received_time', ...), ('version', 3)]
+
+XXX More of the Runner API should be tested.