# `tornado.platform.twisted` — Bridges between Twisted and Tornado

Bridges between the Twisted reactor and Tornado IOLoop.

This module lets you run applications and libraries written for Twisted in a Tornado application. It can be used in two modes, depending on which library’s underlying event loop you want to use.

This module has been tested with Twisted versions 11.0.0 and newer.

## Twisted on Tornado

class `tornado.platform.twisted.``TornadoReactor`(io_loop=None)

  Twisted reactor built on the Tornado IOLoop.

  `TornadoReactor` implements the Twisted reactor interface on top of the Tornado IOLoop. To use it, simply call `install` at the beginning of the application:

      import tornado4.platform.twisted
      tornado4.platform.twisted.install()
      from twisted.internet import reactor

  When the app is ready to start, call `IOLoop.current().start()` instead of `reactor.run()`.

  It is also possible to create a non-global reactor by calling `tornado4.platform.twisted.TornadoReactor(io_loop)`. However, if the `IOLoop` and reactor are to be short-lived (such as those used in unit tests), additional cleanup may be required. Specifically, it is recommended to call:

      reactor.fireSystemEvent('shutdown')
      reactor.disconnectAll()

  before closing the `IOLoop`.

  Changed in version 4.1: The `io_loop` argument is deprecated.

  `seconds`()

    time() -> floating point number

    Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them.

  `callLater`(seconds, f, *args, **kw)

    See twisted.internet.interfaces.IReactorTime.callLater.

  `getDelayedCalls`()

    Return all the outstanding delayed calls in the system. They are returned in no particular order. This method is not efficient – it is really only meant for test cases.

    @return: A list of outstanding delayed calls. @type: L{list} of L{DelayedCall}

  `callFromThread`(f, *args, **kw)

    See L{twisted.internet.interfaces.IReactorFromThreads.callFromThread}.

  `installWaker`()

    Install a `waker’ to allow threads and signals to wake up the IO thread.

    We use the self-pipe trick (http://cr.yp.to/docs/selfpipe.html) to wake the reactor. On Windows we use a pair of sockets.

  `wakeUp`()

    Wake up the event loop.

  `stop`()

    See twisted.internet.interfaces.IReactorCore.stop.

  `crash`()

    See twisted.internet.interfaces.IReactorCore.crash.

    Reset reactor state tracking attributes and re-initialize certain state-transition helpers which were set up in C{__init__} but later destroyed (through use).

  `doIteration`(delay)

    Do one iteration over the readers and writers which have been added.

`tornado.platform.twisted.``install`(io_loop=None)

  Install this package as the default Twisted reactor.

  `install()` must be called very early in the startup process, before most other twisted-related imports. Conversely, because it initializes the `IOLoop`, it cannot be called before `fork_processes` or multi-process `start`. These conflicting requirements make it difficult to use `TornadoReactor` in multi-process mode, and an external process manager such as `supervisord` is recommended instead.

  Changed in version 4.1: The `io_loop` argument is deprecated.

## Tornado on Twisted

class `tornado.platform.twisted.``TwistedIOLoop`

  IOLoop implementation that runs on Twisted.

  `TwistedIOLoop` implements the Tornado IOLoop interface on top of the Twisted reactor. Recommended usage:

      from tornado4.platform.twisted import TwistedIOLoop
      from twisted.internet import reactor
      TwistedIOLoop().install()
      # Set up your tornado application as usual using `IOLoop.instance`
      reactor.run()

  Uses the global Twisted reactor by default. To create multiple `TwistedIOLoops` in the same process, you must pass a unique reactor when constructing each one.

  Not compatible with `tornado4.process.Subprocess.set_exit_callback` because the `SIGCHLD` handlers used by Tornado and Twisted conflict with each other.

  See also `tornado4.ioloop.IOLoop.install()` for general notes on installing alternative IOLoops.

  `initialize`(reactor=None, **kwargs)

    Initialize a `Configurable` subclass instance.

    Configurable classes should use `initialize` instead of `__init__`.

    Changed in version 4.2: Now accepts positional arguments in addition to keyword arguments.

  `close`(all_fds=False)

    Closes the `IOLoop`, freeing any resources used.

    If `all_fds` is true, all file descriptors registered on the IOLoop will be closed (not just the ones created by the `IOLoop` itself).

    Many applications will only use a single `IOLoop` that runs for the entire lifetime of the process. In that case closing the `IOLoop` is not necessary since everything will be cleaned up when the process exits. `IOLoop.close` is provided mainly for scenarios such as unit tests, which create and destroy a large number of `IOLoops`.

    An `IOLoop` must be completely stopped before it can be closed. This means that `IOLoop.stop()` must be called and `IOLoop.start()` must be allowed to return before attempting to call `IOLoop.close()`. Therefore the call to `close` will usually appear just after the call to `start` rather than near the call to `stop`.

    Changed in version 3.1: If the `IOLoop` implementation supports non-integer objects for “file descriptors”, those objects will have their `close` method when `all_fds` is true.

  `add_handler`(fd, handler, events)

    Registers the given handler to receive the given events for `fd`.

    The `fd` argument may either be an integer file descriptor or a file-like object with a `fileno()` method (and optionally a `close()` method, which may be called when the `IOLoop` is shut down).

    The `events` argument is a bitwise or of the constants `IOLoop.READ`, `IOLoop.WRITE`, and `IOLoop.ERROR`.

    When an event occurs, `handler(fd, events)` will be run.

    Changed in version 4.0: Added the ability to pass file-like objects in addition to raw file descriptors.

  `update_handler`(fd, events)

    Changes the events we listen for `fd`.

    Changed in version 4.0: Added the ability to pass file-like objects in addition to raw file descriptors.

  `remove_handler`(fd)

    Stop listening for events on `fd`.

    Changed in version 4.0: Added the ability to pass file-like objects in addition to raw file descriptors.

  `start`()

    Starts the I/O loop.

    The loop will run until one of the callbacks calls `stop()`, which will make the loop stop after the current event iteration completes.

  `stop`()

    Stop the I/O loop.

    If the event loop is not currently running, the next call to `start()` will return immediately.

    To use asynchronous methods from otherwise-synchronous code (such as unit tests), you can start and stop the event loop like this:

        ioloop = IOLoop()
        async_method(ioloop=ioloop, callback=ioloop.stop)
        ioloop.start()

    `ioloop.start()` will return after `async_method` has run its callback, whether that callback was invoked before or after `ioloop.start`.

    Note that even after `stop` has been called, the `IOLoop` is not completely stopped until `IOLoop.start` has also returned. Some work that was scheduled before the call to `stop` may still be run before the `IOLoop` shuts down.

  `add_timeout`(deadline, callback, *args, **kwargs)

    Runs the `callback` at the time `deadline` from the I/O loop.

    Returns an opaque handle that may be passed to `remove_timeout` to cancel.

    `deadline` may be a number denoting a time (on the same scale as `IOLoop.time`, normally `time.time`), or a `datetime.timedelta` object for a deadline relative to the current time. Since Tornado 4.0, `call_later` is a more convenient alternative for the relative case since it does not require a timedelta object.

    Note that it is not safe to call `add_timeout` from other threads. Instead, you must use `add_callback` to transfer control to the `IOLoop`’s thread, and then call `add_timeout` from there.

    Subclasses of IOLoop must implement either `add_timeout` or `call_at`; the default implementations of each will call the other. `call_at` is usually easier to implement, but subclasses that wish to maintain compatibility with Tornado versions prior to 4.0 must use `add_timeout` instead.

    Changed in version 4.0: Now passes through `*args` and `**kwargs` to the callback.

  `remove_timeout`(timeout)

    Cancels a pending timeout.

    The argument is a handle as returned by `add_timeout`. It is safe to call `remove_timeout` even if the callback has already been run.

  `add_callback`(callback, *args, **kwargs)

    Calls the given callback on the next I/O loop iteration.

    It is safe to call this method from any thread at any time, except from a signal handler. Note that this is the only method in `IOLoop` that makes this thread-safety guarantee; all other interaction with the `IOLoop` must be done from that `IOLoop`’s thread. `add_callback()` may be used to transfer control from other threads to the `IOLoop`’s thread.

    To add a callback from a signal handler, see `add_callback_from_signal`.

  `add_callback_from_signal`(callback, *args, **kwargs)

    Calls the given callback on the next I/O loop iteration.

    Safe for use from a Python signal handler; should not be used otherwise.

    Callbacks added with this method will be run without any `stack_context`, to avoid picking up the context of the function that was interrupted by the signal.

## Twisted DNS resolver

class `tornado.platform.twisted.``TwistedResolver`

  Twisted-based asynchronous resolver.

  This is a non-blocking and non-threaded resolver. It is recommended only when threads cannot be used, since it has limitations compared to the standard `getaddrinfo`-based `Resolver` and `ThreadedResolver`. Specifically, it returns at most one result, and arguments other than `host` and `family` are ignored. It may fail to resolve when `family` is not `socket.AF_UNSPEC`.

  Requires Twisted 12.1 or newer.

  Changed in version 4.1: The `io_loop` argument is deprecated.

  `initialize`(io_loop=None)

    Initialize a `Configurable` subclass instance.

    Configurable classes should use `initialize` instead of `__init__`.

    Changed in version 4.2: Now accepts positional arguments in addition to keyword arguments.

  `resolve`(host, port, family=0)

    Resolves an address.

    The `host` argument is a string which may be a hostname or a literal IP address.

    Returns a `Future` whose result is a list of (family, address) pairs, where address is a tuple suitable to pass to `socket.connect` (i.e. a `(host, port)` pair for IPv4; additional fields may be present for IPv6). If a `callback` is passed, it will be run with the result as an argument when it is complete.

    Raises: | IOError – if the address cannot be resolved.

    Changed in version 4.4: Standardized all implementations to raise `IOError`.