
"asyncio" -- Asynchronous I/O, event loop, coroutines and tasks
***************************************************************

Note: The asyncio package has been included in the standard library
  on a *provisional basis*. Backwards incompatible changes (up to and
  including removal of the module) may occur if deemed necessary by
  the core developers.

New in version 3.4.

**Source code:** Lib/asyncio/

======================================================================

This module provides infrastructure for writing single-threaded
concurrent code using coroutines, multiplexing I/O access over sockets
and other resources, running network clients and servers, and other
related primitives. Here is a more detailed list of the package
contents:

* a pluggable *event loop* with various system-specific
  implementations;

* *transport* and *protocol* abstractions (similar to those in
  Twisted);

* concrete support for TCP, UDP, SSL, subprocess pipes, delayed
  calls, and others (some may be system-dependent);

* a "Future" class that mimics the one in the "concurrent.futures"
  module, but adapted for use with the event loop;

* coroutines and tasks based on "yield from" (**PEP 380**), to help
  write concurrent code in a sequential fashion;

* cancellation support for "Future"s and coroutines;

* *synchronization primitives* for use between coroutines in a
  single thread, mimicking those in the "threading" module;

* an interface for passing work off to a threadpool, for times when
  you absolutely, positively have to use a library that makes blocking
  I/O calls.

Asynchronous programming is more complex than classical "sequential"
programming: see the *Develop with asyncio* page which lists common
traps and explains how to avoid them. *Enable the debug mode* during
development to detect common issues.

Table of contents:

* Base Event Loop

  * Run an event loop

  * Calls

  * Delayed calls

  * Tasks

  * Creating connections

  * Creating listening connections

  * Watch file descriptors

  * Low-level socket operations

  * Resolve host name

  * Connect pipes

  * UNIX signals

  * Executor

  * Error Handling API

  * Debug mode

  * Server

  * Handle

  * Event loop examples

    * Hello World with call_soon()

    * Display the current date with call_later()

    * Watch a file descriptor for read events

    * Set signal handlers for SIGINT and SIGTERM

* Event loops

  * Event loop functions

  * Available event loops

  * Platform support

    * Windows

    * Mac OS X

  * Event loop policies and the default policy

  * Event loop policy interface

  * Access to the global loop policy

* Tasks and coroutines

  * Coroutines

    * Example: Hello World coroutine

    * Example: Coroutine displaying the current date

    * Example: Chain coroutines

  * InvalidStateError

  * TimeoutError

  * Future

    * Example: Future with run_until_complete()

    * Example: Future with run_forever()

  * Task

    * Example: Parallel execution of tasks

  * Task functions

* Transports  and protocols (callback based API)

  * Transports

    * BaseTransport

    * ReadTransport

    * WriteTransport

    * DatagramTransport

    * BaseSubprocessTransport

  * Protocols

    * Protocol classes

    * Connection callbacks

    * Streaming protocols

    * Datagram protocols

    * Flow control callbacks

    * Coroutines and protocols

  * Protocol examples

    * TCP echo client protocol

    * TCP echo server protocol

    * UDP echo client protocol

    * UDP echo server protocol

    * Register an open socket to wait for data using a protocol

* Streams (coroutine based API)

  * Stream functions

  * StreamReader

  * StreamWriter

  * StreamReaderProtocol

  * IncompleteReadError

  * Stream examples

    * TCP echo client using streams

    * TCP echo server using streams

    * Get HTTP headers

    * Register an open socket to wait for data using streams

* Subprocess

  * Windows event loop

  * Create a subprocess: high-level API using Process

  * Create a subprocess: low-level API using subprocess.Popen

  * Constants

  * Process

  * Subprocess and threads

  * Subprocess examples

    * Subprocess using transport and protocol

    * Subprocess using streams

* Synchronization primitives

  * Locks

    * Lock

    * Event

    * Condition

  * Semaphores

    * Semaphore

    * BoundedSemaphore

* Queues

  * Queue

  * PriorityQueue

  * LifoQueue

    * JoinableQueue

    * Exceptions

* Develop with asyncio

  * Debug mode of asyncio

  * Cancellation

  * Concurrency and multithreading

  * Handle blocking functions correctly

  * Logging

  * Detect coroutine objects never scheduled

  * Detect exceptions never consumed

  * Chain coroutines correctly

  * Pending task destroyed

  * Close transports and event loops

See also: The "asyncio" module was designed in **PEP 3156**. For a
  motivational primer on transports and protocols, see **PEP 3153**.
