src/mailman/interfaces/runner.py

   1 # Copyright (C) 2007-2012 by the Free Software Foundation, Inc.
   2 #
   3 # This file is part of GNU Mailman.
   4 #
   5 # GNU Mailman is free software: you can redistribute it and/or modify it under
   6 # the terms of the GNU General Public License as published by the Free
   7 # Software Foundation, either version 3 of the License, or (at your option)
   8 # any later version.
   9 #
  10 # GNU Mailman is distributed in the hope that it will be useful, but WITHOUT
  11 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12 # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  13 # more details.
  14 #
  15 # You should have received a copy of the GNU General Public License along with
  16 # GNU Mailman.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 """Interface for runners."""
  19
  20 from __future__ import absolute_import, unicode_literals
  21
  22 __metaclass__ = type
  23 __all__ = [
  24     'IRunner',
  25     'RunnerCrashEvent',
  26     ]
  27
  28
  29 from zope.interface import Interface, Attribute
  30
  31
  32 \f
  33 class RunnerCrashEvent:
  34     """Triggered when a runner encounters an exception in _dispose()."""
  35
  36     def __init__(self, runner, mlist, msg, metadata, error):
  37         self.runner = runner
  38         self.mailing_list = mlist
  39         self.message = msg
  40         self.metadata = metadata
  41         self.error = error
  42
  43
  44 \f
  45 class IRunner(Interface):
  46     """The runner."""
  47
  48     def run():
  49         """Start the runner."""
  50
  51     def stop():
  52         """Stop the runner on the next iteration through the loop."""
  53
  54     queue_directory = Attribute(
  55         'The queue directory.  Overridden in subclasses.')
  56
  57     sleep_time = Attribute("""\
  58         The number of seconds this runner will sleep between iterations
  59         through the main loop.
  60         """)
  61
  62     intercept_signals = Attribute("""\
  63         Should the runner mechanism intercept signals?
  64
  65         In general, the runner catches SIGINT, SIGTERM, SIGUSR1, and SIGHUP to
  66         manage the process.  Some runners need to manage their own signals,
  67         and set this attribute to False.
  68         """)
  69
  70     def _one_iteration():
  71         """The work done in one iteration of the main loop.
  72
  73         Can be overridden by subclasses.
  74
  75         :return: The number of files still left to process.
  76         :rtype: int
  77         """
  78
  79     def _process_one_file(msg, msgdata):
  80         """Process one queue file.
  81
  82         :param msg: The message object.
  83         :type msg: `email.message.Message`
  84         :param msgdata: The message metadata.
  85         :type msgdata: dict
  86         """
  87
  88     def _clean_up():
  89         """Clean up upon exit from the main processing loop.
  90
  91         Called when the runner's main loop is stopped, this should perform any
  92         necessary resource deallocation.
  93         """
  94
  95     def _dispose(mlist, msg, msgdata):
  96         """Dispose of a single message destined for a mailing list.
  97
  98         Called for each message that the runner is responsible for, this is
  99         the primary overridable method for processing each message.
 100         Subclasses, must provide implementation for this method.
 101
 102         :param mlist: The mailing list this message is destined for.
 103         :type mlist: `IMailingList`
 104         :param msg: The message being processed.
 105         :type msg: `email.message.Message`
 106         :param msgdata: The message metadata.
 107         :type msgdata: dict
 108         :return: True if the message should continue to be queued, False if
 109             the message should be deleted automatically.
 110         :rtype: bool
 111         """
 112
 113     def _do_periodic():
 114         """Do some arbitrary periodic processing.
 115
 116         Called every once in a while both from the runner's main loop, and
 117         from the runner's hash slice processing loop.  You can do whatever
 118         special periodic processing you want here.
 119         """
 120
 121     def _snooze(filecnt):
 122         """Sleep for a little while.
 123
 124         :param filecnt: The number of messages in the queue the last time
 125             through.  Runners can decide to continue to do work, or sleep for
 126             a while based on this value.  By default, the base runner only
 127             snoozes when there was nothing to do last time around.
 128         :type filecnt: int
 129         """
 130
 131     def _short_circuit():
 132         """Should processing be short-circuited?
 133
 134         :return: True if the file processing loop should exit before it's
 135             finished processing each message in the current slice of hash
 136             space.  False tells _one_iteration() to continue processing until
 137             the current snapshot of hash space is exhausted.
 138         :rtype: bool
 139         """