18.5. asyncio – Asynchronous I/O, event loop, coroutines and tasks — Python 3.4.10 documentation (original) (raw)

Note

The asyncio package has been included in the standard library on aprovisional 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.futuresmodule, 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.

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:

• 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. Tasks
  • 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.1.17. Event loop examples
    * 18.5.1.17.1. Hello World with call_soon()
    * 18.5.1.17.2. Display the current date with call_later()
    * 18.5.1.17.3. Watch a file descriptor for read events
    * 18.5.1.17.4. Set signal handlers for SIGINT and SIGTERM
• 18.5.2. Event loops
  • 18.5.2.1. Event loop functions
  • 18.5.2.2. Available event loops
  • 18.5.2.3. Platform support
    * 18.5.2.3.1. Windows
    * 18.5.2.3.2. Mac OS X
  • 18.5.2.4. Event loop policies and the default policy
  • 18.5.2.5. Event loop policy interface
  • 18.5.2.6. Access to the global loop policy
• 18.5.3. Tasks and coroutines
  • 18.5.3.1. Coroutines
    * 18.5.3.1.1. Example: Hello World coroutine
    * 18.5.3.1.2. Example: Coroutine displaying the current date
    * 18.5.3.1.3. Example: Chain coroutines
  • 18.5.3.2. InvalidStateError
  • 18.5.3.3. TimeoutError
  • 18.5.3.4. Future
    * 18.5.3.4.1. Example: Future with run_until_complete()
    * 18.5.3.4.2. Example: Future with run_forever()
  • 18.5.3.5. Task
    * 18.5.3.5.1. Example: Parallel execution of tasks
  • 18.5.3.6. Task functions
• 18.5.4. Transports and protocols (callback based API)
  • 18.5.4.1. Transports
    * 18.5.4.1.1. BaseTransport
    * 18.5.4.1.2. ReadTransport
    * 18.5.4.1.3. WriteTransport
    * 18.5.4.1.4. DatagramTransport
    * 18.5.4.1.5. BaseSubprocessTransport
  • 18.5.4.2. Protocols
    * 18.5.4.2.1. Protocol classes
    * 18.5.4.2.2. Connection callbacks
    * 18.5.4.2.3. Streaming protocols
    * 18.5.4.2.4. Datagram protocols
    * 18.5.4.2.5. Flow control callbacks
    * 18.5.4.2.6. Coroutines and protocols
  • 18.5.4.3. Protocol examples
    * 18.5.4.3.1. TCP echo client protocol
    * 18.5.4.3.2. TCP echo server protocol
    * 18.5.4.3.3. UDP echo client protocol
    * 18.5.4.3.4. UDP echo server protocol
    * 18.5.4.3.5. Register an open socket to wait for data using a protocol
• 18.5.5. Streams (coroutine based API)
  • 18.5.5.1. Stream functions
  • 18.5.5.2. StreamReader
  • 18.5.5.3. StreamWriter
  • 18.5.5.4. StreamReaderProtocol
  • 18.5.5.5. IncompleteReadError
  • 18.5.5.6. Stream examples
    * 18.5.5.6.1. TCP echo client using streams
    * 18.5.5.6.2. TCP echo server using streams
    * 18.5.5.6.3. Get HTTP headers
    * 18.5.5.6.4. Register an open socket to wait for data using streams
• 18.5.6. Subprocess
  • 18.5.6.1. Windows event loop
  • 18.5.6.2. Create a subprocess: high-level API using Process
  • 18.5.6.3. Create a subprocess: low-level API using subprocess.Popen
  • 18.5.6.4. Constants
  • 18.5.6.5. Process
  • 18.5.6.6. Subprocess and threads
  • 18.5.6.7. Subprocess examples
    * 18.5.6.7.1. Subprocess using transport and protocol
    * 18.5.6.7.2. Subprocess using streams
• 18.5.7. Synchronization primitives
  • 18.5.7.1. Locks
    * 18.5.7.1.1. Lock
    * 18.5.7.1.2. Event
    * 18.5.7.1.3. Condition
  • 18.5.7.2. Semaphores
    * 18.5.7.2.1. Semaphore
    * 18.5.7.2.2. BoundedSemaphore
• 18.5.8. Queues
  • 18.5.8.1. Queue
  • 18.5.8.2. PriorityQueue
  • 18.5.8.3. LifoQueue
    * 18.5.8.3.1. JoinableQueue
    * 18.5.8.3.2. Exceptions
• 18.5.9. Develop with asyncio
  • 18.5.9.1. Debug mode of asyncio
  • 18.5.9.2. Cancellation
  • 18.5.9.3. Concurrency and multithreading
  • 18.5.9.4. Handle blocking functions correctly
  • 18.5.9.5. Logging
  • 18.5.9.6. Detect coroutine objects never scheduled
  • 18.5.9.7. Detect exceptions never consumed
  • 18.5.9.8. Chain coroutines correctly
  • 18.5.9.9. Pending task destroyed
  • 18.5.9.10. 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.