=============
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 = create_list('_xtest@example.com')

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.