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.