Ticket #5951: ticket-5951-2-docs.patch

File ticket-5951-2-docs.patch, 2.6 KB (added by Ken, 7 years ago)

v2 patch

  • twisted/internet/reactor.py

     
    66applications using Twisted. The reactor provides APIs for networking,
    77threading, dispatching events, and more.
    88
    9 The default reactor depends on the platform and will be installed if this
     9Different platforms have different optimal reactor implementation, thus the
     10default reactor depends on the platform and will be installed if this
    1011module is imported without another reactor being explicitly installed
    11 beforehand. Regardless of which reactor is installed, importing this module is
    12 the correct way to get a reference to it.
     12beforehand.
    1313
    14 New application code should prefer to pass and accept the reactor as a
    15 parameter where it is needed, rather than relying on being able to import this
    16 module to get a reference.  This simplifies unit testing and may make it easier
    17 to one day support multiple reactors (as a performance enhancement), though
    18 this is not currently possible.
     14Importing this module will get a reference to whichever reactor is installed.
     15However, the recommended way to get references to the reactor is to pass and
     16accept the reactor as a parameter where it is needed, and to import the
     17reactor only at the root of the application.  This simplifies unit testing and
     18may make it easier to one day support multiple reactors (as a performance
     19enhancement), though this is not currently possible.
    1920
     21For example, if the library code is::
     22
     23    def doSomethingLater(reactor, *args, **kwargs):
     24        reactor.callLater(5, doSomething, *args, **kwargs)
     25
     26And the application or plugin code has something like::
     27
     28    def makeService(options):
     29        from twisted.internet import reactor
     30        ...
     31        doSomethingLater(reactor, "something")
     32
     33Then the - C{doSomethingLater} function can be tested by passing a
     34L{IReactorTime<twisted.internet.interfaces.IReactorTime>} provider (see
     35L{twisted.internet.task.Clock}).  If the library code imported
     36the reactor instead of accepting it as an argument, then the reactor may need
     37to be monkey-patched with a mocked version when tested.
     38
     39Also, imported the reactor in fewer places makes it easier to debug "reactor
     40already installed" errors, which can happen for example if `twistd` is run
     41with a specified reactor, and the application code imports the reactor
     42too early.
     43
    2044@see: L{IReactorCore<twisted.internet.interfaces.IReactorCore>}
    2145@see: L{IReactorTime<twisted.internet.interfaces.IReactorTime>}
    2246@see: L{IReactorProcess<twisted.internet.interfaces.IReactorProcess>}