Guido van Rossum | 7a46564 | 2013-11-22 11:47:22 -0800 | [diff] [blame] | 1 | :mod:`asyncio` -- Asynchronous I/O, event loop, coroutines and tasks |
| 2 | ==================================================================== |
| 3 | |
| 4 | .. module:: asyncio |
| 5 | :synopsis: Asynchronous I/O, event loop, coroutines and tasks. |
| 6 | |
| 7 | .. versionadded:: 3.4 |
| 8 | |
| 9 | |
Antoine Pitrou | bba8682 | 2013-11-23 00:34:26 +0100 | [diff] [blame^] | 10 | This module provides infrastructure for writing single-threaded concurrent |
| 11 | code using coroutines, multiplexing I/O access over sockets and other |
| 12 | resources, running network clients and servers, and other related primitives. |
Guido van Rossum | 7a46564 | 2013-11-22 11:47:22 -0800 | [diff] [blame] | 13 | |
Antoine Pitrou | bba8682 | 2013-11-23 00:34:26 +0100 | [diff] [blame^] | 14 | Here is a more detailed list of the package contents: |
| 15 | |
| 16 | * a pluggable :ref:`event loop <event-loop>` with various system-specific |
| 17 | implementations; |
| 18 | |
| 19 | * :ref:`transport <transport>` and :ref:`protocol <protocol>` abstractions |
| 20 | (similar to those in `Twisted <http://twistedmatrix.com/>`_); |
| 21 | |
| 22 | * concrete support for TCP, UDP, SSL, subprocess pipes, delayed calls, and |
| 23 | others (some may be system-dependent); |
| 24 | |
| 25 | * a Future class that mimicks the one in the :mod:`concurrent.futures` module, |
| 26 | but adapted for use with the event loop; |
| 27 | |
| 28 | * coroutines and tasks based on ``yield from`` (:PEP:`380`), to help write |
| 29 | concurrent code in a sequential fashion; |
| 30 | |
| 31 | * cancellation support for Futures and coroutines; |
| 32 | |
| 33 | * :ref:`synchronization primitives <sync>` for use between coroutines in |
| 34 | a single thread, mimicking those in the :mod:`threading` module; |
| 35 | |
| 36 | |
| 37 | Disclaimer |
| 38 | ---------- |
Guido van Rossum | 7a46564 | 2013-11-22 11:47:22 -0800 | [diff] [blame] | 39 | |
| 40 | Full documentation is not yet ready; we hope to have it written |
| 41 | before Python 3.4 leaves beta. Until then, the best reference is |
| 42 | :PEP:`3156`. For a motivational primer on transports and protocols, |
| 43 | see :PEP:`3153`. |
Antoine Pitrou | bba8682 | 2013-11-23 00:34:26 +0100 | [diff] [blame^] | 44 | |
| 45 | |
| 46 | .. XXX should the asyncio documentation come in several pages, as for logging? |
| 47 | |
| 48 | |
| 49 | .. _event-loop: |
| 50 | |
| 51 | Event loops |
| 52 | ----------- |
| 53 | |
| 54 | |
| 55 | .. _protocol: |
| 56 | |
| 57 | Protocols |
| 58 | --------- |
| 59 | |
| 60 | |
| 61 | .. _transport: |
| 62 | |
| 63 | Transports |
| 64 | ---------- |
| 65 | |
| 66 | |
| 67 | .. _sync: |
| 68 | |
| 69 | Synchronization primitives |
| 70 | -------------------------- |
| 71 | |
| 72 | |
| 73 | Examples |
| 74 | -------- |
| 75 | |
| 76 | A :class:`Protocol` implementing an echo server:: |
| 77 | |
| 78 | class EchoServer(asyncio.Protocol): |
| 79 | |
| 80 | TIMEOUT = 5.0 |
| 81 | |
| 82 | def timeout(self): |
| 83 | print('connection timeout, closing.') |
| 84 | self.transport.close() |
| 85 | |
| 86 | def connection_made(self, transport): |
| 87 | print('connection made') |
| 88 | self.transport = transport |
| 89 | |
| 90 | # start 5 seconds timeout timer |
| 91 | self.h_timeout = asyncio.get_event_loop().call_later( |
| 92 | self.TIMEOUT, self.timeout) |
| 93 | |
| 94 | def data_received(self, data): |
| 95 | print('data received: ', data.decode()) |
| 96 | self.transport.write(b'Re: ' + data) |
| 97 | |
| 98 | # restart timeout timer |
| 99 | self.h_timeout.cancel() |
| 100 | self.h_timeout = asyncio.get_event_loop().call_later( |
| 101 | self.TIMEOUT, self.timeout) |
| 102 | |
| 103 | def eof_received(self): |
| 104 | pass |
| 105 | |
| 106 | def connection_lost(self, exc): |
| 107 | print('connection lost:', exc) |
| 108 | self.h_timeout.cancel() |
| 109 | |