twisted/application/reactors.py

   1 # -*- test-case-name: twisted.test.test_application -*-
   2 # Copyright (c) Twisted Matrix Laboratories.
   3 # See LICENSE for details.
   4
   5 """
   6 Plugin-based system for enumerating available reactors and installing one of
   7 them.
   8 """
   9
  10 from zope.interface import Interface, Attribute, implements
  11
  12 from twisted.plugin import IPlugin, getPlugins
  13 from twisted.python.reflect import namedAny
  14
  15
  16 class IReactorInstaller(Interface):
  17     """
  18     Definition of a reactor which can probably be installed.
  19     """
  20     shortName = Attribute("""
  21     A brief string giving the user-facing name of this reactor.
  22     """)
  23
  24     description = Attribute("""
  25     A longer string giving a user-facing description of this reactor.
  26     """)
  27
  28     def install():
  29         """
  30         Install this reactor.
  31         """
  32
  33     # TODO - A method which provides a best-guess as to whether this reactor
  34     # can actually be used in the execution environment.
  35
  36
  37
  38 class NoSuchReactor(KeyError):
  39     """
  40     Raised when an attempt is made to install a reactor which cannot be found.
  41     """
  42
  43
  44 class Reactor(object):
  45     """
  46     @ivar moduleName: The fully-qualified Python name of the module of which
  47     the install callable is an attribute.
  48     """
  49     implements(IPlugin, IReactorInstaller)
  50
  51
  52     def __init__(self, shortName, moduleName, description):
  53         self.shortName = shortName
  54         self.moduleName = moduleName
  55         self.description = description
  56
  57
  58     def install(self):
  59         namedAny(self.moduleName).install()
  60
  61
  62
  63 def getReactorTypes():
  64     """
  65     Return an iterator of L{IReactorInstaller} plugins.
  66     """
  67     return getPlugins(IReactorInstaller)
  68
  69
  70
  71 def installReactor(shortName):
  72     """
  73     Install the reactor with the given C{shortName} attribute.
  74
  75     @raise NoSuchReactor: If no reactor is found with a matching C{shortName}.
  76
  77     @raise: anything that the specified reactor can raise when installed.
  78     """
  79     for installer in getReactorTypes():
  80         if installer.shortName == shortName:
  81             return installer.install()
  82     raise NoSuchReactor(shortName)
  83