# `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`.