tornado.platform.asyncio — Bridge between asyncio and Tornado

Bridges between the asyncio module and Tornado IOLoop.

New in version 3.2.

This module integrates Tornado with the asyncio module introduced in Python 3.4 (and available as a separate download for Python 3.3). This makes it possible to combine the two libraries on the same event loop.

Most applications should use AsyncIOMainLoop to run Tornado on the default asyncio event loop. Applications that need to run event loops on multiple threads may use AsyncIOLoop to create multiple loops.

Note

Tornado requires the add_reader family of methods, so it is not compatible with the ProactorEventLoop on Windows. Use the SelectorEventLoop instead.

class tornado.platform.asyncio.BaseAsyncIOLoop

initialize(asyncio_loop, close_loop=False, **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.

call_at(when, callback, *args, **kwargs)

Runs the callback at the absolute time designated by when.

when must be a number using the same reference point as IOLoop.time.

Returns an opaque handle that may be passed to remove_timeout to cancel. Note that unlike the asyncio method of the same name, the returned object does not have a cancel() method.

See add_timeout for comments on thread-safety and subclassing.

New in version 4.0.

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.

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.

class tornado.platform.asyncio.AsyncIOMainLoop

AsyncIOMainLoop creates an IOLoop that corresponds to the current asyncio event loop (i.e. the one returned by asyncio.get_event_loop()). Recommended usage:

from tornado4.platform.asyncio import AsyncIOMainLoop
import asyncio
AsyncIOMainLoop().install()
asyncio.get_event_loop().run_forever()

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

initialize(**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.

class tornado.platform.asyncio.AsyncIOLoop

AsyncIOLoop is an IOLoop that runs on an asyncio event loop. This class follows the usual Tornado semantics for creating new IOLoops; these loops are not necessarily related to the asyncio default event loop. Recommended usage:

from tornado4.ioloop import IOLoop
IOLoop.configure('tornado4.platform.asyncio.AsyncIOLoop')
IOLoop.current().start()

Each AsyncIOLoop creates a new asyncio.EventLoop; this object can be accessed with the asyncio_loop attribute.

initialize(**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.

tornado.platform.asyncio.to_tornado_future(asyncio_future)

Convert an asyncio.Future to a tornado4.concurrent.Future.

New in version 4.1.

tornado.platform.asyncio.to_asyncio_future(tornado_future)

Convert a Tornado yieldable object to an asyncio.Future.

New in version 4.1.

Changed in version 4.3: Now accepts any yieldable object, not just tornado4.concurrent.Future.