18.5. 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 Futures 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.

Table of contents:

• 18.5.1. Base Event Loop
  • 18.5.1.1. Run an event loop
  • 18.5.1.2. Calls
  • 18.5.1.3. Delayed calls
  • 18.5.1.4. Coroutines
  • 18.5.1.5. Creating connections
  • 18.5.1.6. Creating listening connections
  • 18.5.1.7. Watch file descriptors
  • 18.5.1.8. Low-level socket operations
  • 18.5.1.9. Resolve host name
  • 18.5.1.10. Connect pipes
  • 18.5.1.11. UNIX signals
  • 18.5.1.12. Executor
  • 18.5.1.13. Error Handling API
  • 18.5.1.14. Debug mode
  • 18.5.1.15. Server
  • 18.5.1.16. Handle
• 18.5.2. Event loop examples
  • 18.5.2.1. Hello World with call_soon()
  • 18.5.2.2. Display the current date with call_later()
  • 18.5.2.3. Watch a file descriptor for read events
  • 18.5.2.4. Set signal handlers for SIGINT and SIGTERM
• 18.5.3. Event loops
  • 18.5.3.1. Event loop functions
  • 18.5.3.2. Available event loops
  • 18.5.3.3. Platform support
    • 18.5.3.3.1. Windows
    • 18.5.3.3.2. Mac OS X
  • 18.5.3.4. Event loop policies and the default policy
  • 18.5.3.5. Event loop policy interface
  • 18.5.3.6. Access to the global loop policy
• 18.5.4. Tasks and coroutines
  • 18.5.4.1. Coroutines
    • 18.5.4.1.1. Example: Hello World coroutine
    • 18.5.4.1.2. Example: Coroutine displaying the current date
    • 18.5.4.1.3. Example: Chain coroutines
  • 18.5.4.2. InvalidStateError
  • 18.5.4.3. TimeoutError
  • 18.5.4.4. Future
    • 18.5.4.4.1. Example: Future with run_until_complete()
    • 18.5.4.4.2. Example: Future with run_forever()
  • 18.5.4.5. Task
    • 18.5.4.5.1. Example: Parallel execution of tasks
  • 18.5.4.6. Task functions
• 18.5.5. Transports and protocols (low-level API)
  • 18.5.5.1. Transports
    • 18.5.5.1.1. BaseTransport
    • 18.5.5.1.2. ReadTransport
    • 18.5.5.1.3. WriteTransport
    • 18.5.5.1.4. DatagramTransport
    • 18.5.5.1.5. BaseSubprocessTransport
  • 18.5.5.2. Protocols
    • 18.5.5.2.1. Protocol classes
    • 18.5.5.2.2. Connection callbacks
    • 18.5.5.2.3. Streaming protocols
    • 18.5.5.2.4. Datagram protocols
    • 18.5.5.2.5. Flow control callbacks
    • 18.5.5.2.6. Coroutines and protocols
  • 18.5.5.3. Protocol examples
    • 18.5.5.3.1. TCP echo client protocol
    • 18.5.5.3.2. TCP echo server protocol
    • 18.5.5.3.3. UDP echo client protocol
    • 18.5.5.3.4. UDP echo server protocol
    • 18.5.5.3.5. Register an open socket to wait for data using a protocol
• 18.5.6. Streams (high-level API)
  • 18.5.6.1. Stream functions
  • 18.5.6.2. StreamReader
  • 18.5.6.3. StreamWriter
  • 18.5.6.4. StreamReaderProtocol
  • 18.5.6.5. IncompleteReadError
  • 18.5.6.6. Stream examples
    • 18.5.6.6.1. TCP echo client using streams
    • 18.5.6.6.2. TCP echo server using streams
    • 18.5.6.6.3. Get HTTP headers
    • 18.5.6.6.4. Register an open socket to wait for data using streams
• 18.5.7. Subprocess
  • 18.5.7.1. Windows event loop
  • 18.5.7.2. Create a subprocess: high-level API using Process
  • 18.5.7.3. Create a subprocess: low-level API using subprocess.Popen
  • 18.5.7.4. Constants
  • 18.5.7.5. Process
• 18.5.8. Subprocess examples
  • 18.5.8.1. Subprocess using transport and protocol
  • 18.5.8.2. Subprocess using streams
• 18.5.9. Synchronization primitives
  • 18.5.9.1. Locks
    • 18.5.9.1.1. Lock
    • 18.5.9.1.2. Event
    • 18.5.9.1.3. Condition
  • 18.5.9.2. Semaphores
    • 18.5.9.2.1. Semaphore
    • 18.5.9.2.2. BoundedSemaphore
  • 18.5.9.3. Queues
    • 18.5.9.3.1. Queue
    • 18.5.9.3.2. PriorityQueue
    • 18.5.9.3.3. LifoQueue
    • 18.5.9.3.4. JoinableQueue
    • 18.5.9.3.5. Exceptions
• 18.5.10. Develop with asyncio
  • 18.5.10.1. Debug mode of asyncio
  • 18.5.10.2. Concurrency and multithreading
  • 18.5.10.3. Handle blocking functions correctly
  • 18.5.10.4. Logging
  • 18.5.10.5. Detect coroutine objects never scheduled
  • 18.5.10.6. Detect exceptions never consumed
  • 18.5.10.7. Chain correctly coroutines
  • 18.5.10.8. Pending task destroyed

See also

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