1 files changed, 49 insertions, 0 deletions
diff --git a/src/mailman/bin/docs/master.txt b/src/mailman/bin/docs/master.txt
new file mode 100644
index 000000000..0d3cade77
--- /dev/null
+++ b/src/mailman/bin/docs/master.txt
@@ -0,0 +1,49 @@
+Mailman queue runner control
+============================
+
+Mailman has a number of queue runners which process messages in its queue file
+directories.  In normal operation, a command line script called 'mailmanctl'
+is used to start, stop and manage the queue runners.  mailmanctl actually is
+just a wrapper around the real queue runner watcher script called master.py.
+
+    >>> from mailman.testing.helpers import TestableMaster
+
+Start the master in a subthread.
+
+    >>> master = TestableMaster()
+    >>> master.start()
+
+There should be a process id for every qrunner that claims to be startable.
+
+    >>> from lazr.config import as_boolean
+    >>> startable_qrunners = [qconf for qconf in config.qrunner_configs
+    ...                       if as_boolean(qconf.start)]
+    >>> len(list(master.qrunner_pids)) == len(startable_qrunners)
+    True
+
+Now verify that all the qrunners are running.
+
+    >>> import os
+
+    # This should produce no output.
+    >>> for pid in master.qrunner_pids:
+    ...     os.kill(pid, 0)
+
+Stop the master process, which should also kill (and not restart) the child
+queue runner processes.
+
+    >>> master.stop()
+
+None of the children are running now.
+
+    >>> import errno
+    >>> for pid in master.qrunner_pids:
+    ...     try:
+    ...         os.kill(pid, 0)
+    ...         print 'Process did not exit:', pid
+    ...     except OSError, error:
+    ...         if error.errno == errno.ESRCH:
+    ...             # The child process exited.
+    ...             pass
+    ...         else:
+    ...             raise