src/mailman/interfaces/runner.py

   1 # Copyright (C) 2007-2016 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 mailman import public
  21 from zope.interface import Attribute, Interface
  22
  23
  24 @public
  25 class RunnerCrashEvent:
  26     """Triggered when a runner encounters an exception in _dispose()."""
  27
  28     def __init__(self, runner, mlist, msg, metadata, error):
  29         self.runner = runner
  30         self.mailing_list = mlist
  31         self.message = msg
  32         self.metadata = metadata
  33         self.error = error
  34
  35
  36 @public
  37 class IRunner(Interface):
  38     """The runner."""
  39
  40     def run():
  41         """Start the runner."""
  42
  43     def stop():
  44         """Stop the runner on the next iteration through the loop."""
  45
  46     is_queue_runner = Attribute("""\
  47         A boolean variable describing whether the runner is a queue runner.
  48         """)
  49
  50     queue_directory = Attribute(
  51         'The queue directory.  Overridden in subclasses.')
  52
  53     sleep_time = Attribute("""\
  54         The number of seconds this runner will sleep between iterations
  55         through the main loop.
  56         """)
  57
  58     def set_signals():
  59         """Set up the signal handlers necessary to control the runner.
  60
  61         The runner should catch the following signals:
  62         - SIGTERM and SIGINT: treated exactly the same, they cause the runner
  63           to exit with no restart from the master.
  64         - SIGUSR1: Also causes the runner to exit, but the master watcher will
  65           retart it.
  66         - SIGHUP: Re-open the log files.
  67         """
  68
  69     def _one_iteration():
  70         """The work done in one iteration of the main loop.
  71
  72         Can be overridden by subclasses.
  73
  74         :return: The number of files still left to process.
  75         :rtype: int
  76         """
  77
  78     def _process_one_file(msg, msgdata):
  79         """Process one queue file.
  80
  81         :param msg: The message object.
  82         :type msg: `email.message.Message`
  83         :param msgdata: The message metadata.
  84         :type msgdata: dict
  85         """
  86
  87     def _clean_up():
  88         """Clean up upon exit from the main processing loop.
  89
  90         Called when the runner's main loop is stopped, this should perform any
  91         necessary resource deallocation.
  92         """
  93
  94     def _dispose(mlist, msg, msgdata):
  95         """Dispose of a single message destined for a mailing list.
  96
  97         Called for each message that the runner is responsible for, this is
  98         the primary overridable method for processing each message.
  99         Subclasses, must provide implementation for this method.
 100
 101         :param mlist: The mailing list this message is destined for.
 102         :type mlist: `IMailingList`
 103         :param msg: The message being processed.
 104         :type msg: `email.message.Message`
 105         :param msgdata: The message metadata.
 106         :type msgdata: dict
 107         :return: True if the message should continue to be queued, False if
 108             the message should be deleted automatically.
 109         :rtype: bool
 110         """
 111
 112     def _do_periodic():
 113         """Do some arbitrary periodic processing.
 114
 115         Called every once in a while both from the runner's main loop, and
 116         from the runner's hash slice processing loop.  You can do whatever
 117         special periodic processing you want here.
 118         """
 119
 120     def _snooze(filecnt):
 121         """Sleep for a little while.
 122
 123         :param filecnt: The number of messages in the queue the last time
 124             through.  Runners can decide to continue to do work, or sleep for
 125             a while based on this value.  By default, the base runner only
 126             snoozes when there was nothing to do last time around.
 127         :type filecnt: int
 128         """
 129
 130     def _short_circuit():
 131         """Should processing be short-circuited?
 132
 133         :return: True if the file processing loop should exit before it's
 134             finished processing each message in the current slice of hash
 135             space.  False tells _one_iteration() to continue processing until
 136             the current snapshot of hash space is exhausted.
 137         :rtype: bool
 138         """