buildbot/slave/interfaces.py

   1 #! /usr/bin/python
   2
   3 from buildbot.twcompat import Interface
   4
   5 class ISlaveCommand(Interface):
   6     """This interface is implemented by all of the buildslave's Command
   7     subclasses. It specifies how the buildslave can start, interrupt, and
   8     query the various Commands running on behalf of the buildmaster."""
   9
  10     def __init__(builder, stepId, args):
  11         """Create the Command. 'builder' is a reference to the parent
  12         buildbot.bot.SlaveBuilder instance, which will be used to send status
  13         updates (by calling builder.sendStatus). 'stepId' is a random string
  14         which helps correlate slave logs with the master. 'args' is a dict of
  15         arguments that comes from the master-side BuildStep, with contents
  16         that are specific to the individual Command subclass.
  17
  18         This method is not intended to be subclassed."""
  19
  20     def setup(args):
  21         """This method is provided for subclasses to override, to extract
  22         parameters from the 'args' dictionary. The default implemention does
  23         nothing. It will be called from __init__"""
  24
  25     def start():
  26         """Begin the command, and return a Deferred.
  27
  28         While the command runs, it should send status updates to the
  29         master-side BuildStep by calling self.sendStatus(status). The
  30         'status' argument is typically a dict with keys like 'stdout',
  31         'stderr', and 'rc'.
  32
  33         When the step completes, it should fire the Deferred (the results are
  34         not used). If an exception occurs during execution, it may also
  35         errback the deferred, however any reasonable errors should be trapped
  36         and indicated with a non-zero 'rc' status rather than raising an
  37         exception. Exceptions should indicate problems within the buildbot
  38         itself, not problems in the project being tested.
  39
  40         """
  41
  42     def interrupt():
  43         """This is called to tell the Command that the build is being stopped
  44         and therefore the command should be terminated as quickly as
  45         possible. The command may continue to send status updates, up to and
  46         including an 'rc' end-of-command update (which should indicate an
  47         error condition). The Command's deferred should still be fired when
  48         the command has finally completed.
  49
  50         If the build is being stopped because the slave it shutting down or
  51         because the connection to the buildmaster has been lost, the status
  52         updates will simply be discarded. The Command does not need to be
  53         aware of this.
  54
  55         Child shell processes should be killed. Simple ShellCommand classes
  56         can just insert a header line indicating that the process will be
  57         killed, then os.kill() the child."""