R David Murray | 6a14381 | 2013-12-20 14:37:39 -0500 | [diff] [blame] | 1 | .. currentmodule:: asyncio |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 2 | |
Victor Stinner | 1374bd4 | 2014-01-24 15:34:19 +0100 | [diff] [blame] | 3 | +++++++++++++++++++++++++++++++++++++++++ |
| 4 | Transports and protocols (low-level API) |
| 5 | +++++++++++++++++++++++++++++++++++++++++ |
Victor Stinner | 1ca5ba6 | 2013-12-03 01:49:43 +0100 | [diff] [blame] | 6 | |
Victor Stinner | 9592edb | 2014-02-02 15:03:02 +0100 | [diff] [blame] | 7 | .. _asyncio-transport: |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 8 | |
| 9 | Transports |
| 10 | ========== |
| 11 | |
Guido van Rossum | 589872c | 2014-03-29 21:14:04 -0700 | [diff] [blame] | 12 | Transports are classes provided by :mod:`asyncio` in order to abstract |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 13 | various kinds of communication channels. You generally won't instantiate |
| 14 | a transport yourself; instead, you will call a :class:`BaseEventLoop` method |
| 15 | which will create the transport and try to initiate the underlying |
| 16 | communication channel, calling you back when it succeeds. |
| 17 | |
| 18 | Once the communication channel is established, a transport is always |
Victor Stinner | 9592edb | 2014-02-02 15:03:02 +0100 | [diff] [blame] | 19 | paired with a :ref:`protocol <asyncio-protocol>` instance. The protocol can |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 20 | then call the transport's methods for various purposes. |
| 21 | |
| 22 | :mod:`asyncio` currently implements transports for TCP, UDP, SSL, and |
| 23 | subprocess pipes. The methods available on a transport depend on |
| 24 | the transport's kind. |
| 25 | |
| 26 | |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 27 | BaseTransport |
| 28 | ------------- |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 29 | |
| 30 | .. class:: BaseTransport |
| 31 | |
| 32 | Base class for transports. |
| 33 | |
| 34 | .. method:: close(self) |
| 35 | |
| 36 | Close the transport. If the transport has a buffer for outgoing |
| 37 | data, buffered data will be flushed asynchronously. No more data |
| 38 | will be received. After all buffered data is flushed, the |
| 39 | protocol's :meth:`connection_lost` method will be called with |
| 40 | :const:`None` as its argument. |
| 41 | |
| 42 | |
| 43 | .. method:: get_extra_info(name, default=None) |
| 44 | |
| 45 | Return optional transport information. *name* is a string representing |
| 46 | the piece of transport-specific information to get, *default* is the |
| 47 | value to return if the information doesn't exist. |
| 48 | |
| 49 | This method allows transport implementations to easily expose |
| 50 | channel-specific information. |
| 51 | |
| 52 | * socket: |
| 53 | |
| 54 | - ``'peername'``: the remote address to which the socket is connected, |
| 55 | result of :meth:`socket.socket.getpeername` (``None`` on error) |
| 56 | - ``'socket'``: :class:`socket.socket` instance |
| 57 | - ``'sockname'``: the socket's own address, |
| 58 | result of :meth:`socket.socket.getsockname` |
| 59 | |
| 60 | * SSL socket: |
| 61 | |
| 62 | - ``'compression'``: the compression algorithm being used as a string, |
| 63 | or ``None`` if the connection isn't compressed; result of |
| 64 | :meth:`ssl.SSLSocket.compression` |
| 65 | - ``'cipher'``: a three-value tuple containing the name of the cipher |
| 66 | being used, the version of the SSL protocol that defines its use, and |
| 67 | the number of secret bits being used; result of |
| 68 | :meth:`ssl.SSLSocket.cipher` |
| 69 | - ``'peercert'``: peer certificate; result of |
| 70 | :meth:`ssl.SSLSocket.getpeercert` |
| 71 | - ``'sslcontext'``: :class:`ssl.SSLContext` instance |
| 72 | |
| 73 | * pipe: |
| 74 | |
| 75 | - ``'pipe'``: pipe object |
| 76 | |
| 77 | * subprocess: |
| 78 | |
| 79 | - ``'subprocess'``: :class:`subprocess.Popen` instance |
| 80 | |
| 81 | |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 82 | ReadTransport |
| 83 | ------------- |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 84 | |
| 85 | .. class:: ReadTransport |
| 86 | |
| 87 | Interface for read-only transports. |
| 88 | |
| 89 | .. method:: pause_reading() |
| 90 | |
| 91 | Pause the receiving end of the transport. No data will be passed to |
Victor Stinner | 51f3129 | 2014-03-21 17:17:15 +0100 | [diff] [blame] | 92 | the protocol's :meth:`data_received` method until :meth:`resume_reading` |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 93 | is called. |
| 94 | |
| 95 | .. method:: resume_reading() |
| 96 | |
| 97 | Resume the receiving end. The protocol's :meth:`data_received` method |
| 98 | will be called once again if some data is available for reading. |
| 99 | |
| 100 | |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 101 | WriteTransport |
| 102 | -------------- |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 103 | |
| 104 | .. class:: WriteTransport |
| 105 | |
| 106 | Interface for write-only transports. |
| 107 | |
| 108 | .. method:: abort() |
| 109 | |
| 110 | Close the transport immediately, without waiting for pending operations |
| 111 | to complete. Buffered data will be lost. No more data will be received. |
| 112 | The protocol's :meth:`connection_lost` method will eventually be |
| 113 | called with :const:`None` as its argument. |
| 114 | |
| 115 | .. method:: can_write_eof() |
| 116 | |
| 117 | Return :const:`True` if the transport supports :meth:`write_eof`, |
| 118 | :const:`False` if not. |
| 119 | |
| 120 | .. method:: get_write_buffer_size() |
| 121 | |
| 122 | Return the current size of the output buffer used by the transport. |
| 123 | |
Victor Stinner | 52bb949 | 2014-08-26 00:22:28 +0200 | [diff] [blame] | 124 | .. method:: get_write_buffer_limits() |
| 125 | |
| 126 | Get the *high*- and *low*-water limits for write flow control. Return a |
| 127 | tuple ``(low, high)`` where *low* and *high* are positive number of |
| 128 | bytes. |
| 129 | |
| 130 | Use :meth:`set_write_buffer_limits` to set the limits. |
| 131 | |
| 132 | .. versionadded:: 3.4.2 |
| 133 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 134 | .. method:: set_write_buffer_limits(high=None, low=None) |
| 135 | |
| 136 | Set the *high*- and *low*-water limits for write flow control. |
| 137 | |
| 138 | These two values control when call the protocol's |
| 139 | :meth:`pause_writing` and :meth:`resume_writing` methods are called. |
| 140 | If specified, the low-water limit must be less than or equal to the |
| 141 | high-water limit. Neither *high* nor *low* can be negative. |
| 142 | |
| 143 | The defaults are implementation-specific. If only the |
| 144 | high-water limit is given, the low-water limit defaults to a |
| 145 | implementation-specific value less than or equal to the |
| 146 | high-water limit. Setting *high* to zero forces *low* to zero as |
| 147 | well, and causes :meth:`pause_writing` to be called whenever the |
| 148 | buffer becomes non-empty. Setting *low* to zero causes |
| 149 | :meth:`resume_writing` to be called only once the buffer is empty. |
| 150 | Use of zero for either limit is generally sub-optimal as it |
| 151 | reduces opportunities for doing I/O and computation |
| 152 | concurrently. |
| 153 | |
Victor Stinner | 52bb949 | 2014-08-26 00:22:28 +0200 | [diff] [blame] | 154 | Use :meth:`get_write_buffer_limits` to get the limits. |
| 155 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 156 | .. method:: write(data) |
| 157 | |
| 158 | Write some *data* bytes to the transport. |
| 159 | |
| 160 | This method does not block; it buffers the data and arranges for it |
| 161 | to be sent out asynchronously. |
| 162 | |
| 163 | .. method:: writelines(list_of_data) |
| 164 | |
| 165 | Write a list (or any iterable) of data bytes to the transport. |
| 166 | This is functionally equivalent to calling :meth:`write` on each |
| 167 | element yielded by the iterable, but may be implemented more efficiently. |
| 168 | |
| 169 | .. method:: write_eof() |
| 170 | |
| 171 | Close the write end of the transport after flushing buffered data. |
| 172 | Data may still be received. |
| 173 | |
| 174 | This method can raise :exc:`NotImplementedError` if the transport |
| 175 | (e.g. SSL) doesn't support half-closes. |
| 176 | |
| 177 | |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 178 | DatagramTransport |
| 179 | ----------------- |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 180 | |
| 181 | .. method:: DatagramTransport.sendto(data, addr=None) |
| 182 | |
| 183 | Send the *data* bytes to the remote peer given by *addr* (a |
| 184 | transport-dependent target address). If *addr* is :const:`None`, the |
| 185 | data is sent to the target address given on transport creation. |
| 186 | |
| 187 | This method does not block; it buffers the data and arranges for it |
| 188 | to be sent out asynchronously. |
| 189 | |
| 190 | .. method:: DatagramTransport.abort() |
| 191 | |
| 192 | Close the transport immediately, without waiting for pending operations |
| 193 | to complete. Buffered data will be lost. No more data will be received. |
| 194 | The protocol's :meth:`connection_lost` method will eventually be |
| 195 | called with :const:`None` as its argument. |
| 196 | |
| 197 | |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 198 | BaseSubprocessTransport |
| 199 | ----------------------- |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 200 | |
| 201 | .. class:: BaseSubprocessTransport |
| 202 | |
| 203 | .. method:: get_pid() |
| 204 | |
| 205 | Return the subprocess process id as an integer. |
| 206 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 207 | .. method:: get_pipe_transport(fd) |
| 208 | |
Brian Curtin | a1afeec | 2014-02-08 18:36:14 -0600 | [diff] [blame] | 209 | Return the transport for the communication pipe corresponding to the |
Victor Stinner | 4270a24 | 2014-10-13 23:56:43 +0200 | [diff] [blame] | 210 | integer file descriptor *fd*: |
| 211 | |
| 212 | * ``0``: readable streaming transport of the standard input (*stdin*), |
| 213 | or :const:`None` if the subprocess was not created with ``stdin=PIPE`` |
| 214 | * ``1``: writable streaming transport of the standard output (*stdout*), |
| 215 | or :const:`None` if the subprocess was not created with ``stdout=PIPE`` |
| 216 | * ``2``: writable streaming transport of the standard error (*stderr*), |
| 217 | or :const:`None` if the subprocess was not created with ``stderr=PIPE`` |
| 218 | * other *fd*: :const:`None` |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 219 | |
Victor Stinner | 933a8c8 | 2013-12-03 01:59:38 +0100 | [diff] [blame] | 220 | .. method:: get_returncode() |
| 221 | |
| 222 | Return the subprocess returncode as an integer or :const:`None` |
| 223 | if it hasn't returned, similarly to the |
| 224 | :attr:`subprocess.Popen.returncode` attribute. |
| 225 | |
| 226 | .. method:: kill(self) |
| 227 | |
| 228 | Kill the subprocess, as in :meth:`subprocess.Popen.kill` |
| 229 | |
| 230 | On POSIX systems, the function sends SIGKILL to the subprocess. |
| 231 | On Windows, this method is an alias for :meth:`terminate`. |
| 232 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 233 | .. method:: send_signal(signal) |
| 234 | |
| 235 | Send the *signal* number to the subprocess, as in |
| 236 | :meth:`subprocess.Popen.send_signal`. |
| 237 | |
| 238 | .. method:: terminate() |
| 239 | |
| 240 | Ask the subprocess to stop, as in :meth:`subprocess.Popen.terminate`. |
| 241 | This method is an alias for the :meth:`close` method. |
| 242 | |
| 243 | On POSIX systems, this method sends SIGTERM to the subprocess. |
| 244 | On Windows, the Windows API function TerminateProcess() is called to |
| 245 | stop the subprocess. |
| 246 | |
Victor Stinner | 4270a24 | 2014-10-13 23:56:43 +0200 | [diff] [blame] | 247 | .. method:: close() |
| 248 | |
| 249 | Ask the subprocess to stop by calling the :meth:`terminate` method if the |
| 250 | subprocess hasn't returned yet, and close transports of all pipes |
| 251 | (*stdin*, *stdout* and *stderr*). |
| 252 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 253 | |
Victor Stinner | 9592edb | 2014-02-02 15:03:02 +0100 | [diff] [blame] | 254 | .. _asyncio-protocol: |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 255 | |
| 256 | Protocols |
| 257 | ========= |
| 258 | |
| 259 | :mod:`asyncio` provides base classes that you can subclass to implement |
| 260 | your network protocols. Those classes are used in conjunction with |
Victor Stinner | 9592edb | 2014-02-02 15:03:02 +0100 | [diff] [blame] | 261 | :ref:`transports <asyncio-transport>` (see below): the protocol parses incoming |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 262 | data and asks for the writing of outgoing data, while the transport is |
| 263 | responsible for the actual I/O and buffering. |
| 264 | |
| 265 | When subclassing a protocol class, it is recommended you override certain |
| 266 | methods. Those methods are callbacks: they will be called by the transport |
| 267 | on certain events (for example when some data is received); you shouldn't |
| 268 | call them yourself, unless you are implementing a transport. |
| 269 | |
| 270 | .. note:: |
| 271 | All callbacks have default implementations, which are empty. Therefore, |
| 272 | you only need to implement the callbacks for the events in which you |
| 273 | are interested. |
| 274 | |
| 275 | |
| 276 | Protocol classes |
| 277 | ---------------- |
| 278 | |
| 279 | .. class:: Protocol |
| 280 | |
| 281 | The base class for implementing streaming protocols (for use with |
| 282 | e.g. TCP and SSL transports). |
| 283 | |
| 284 | .. class:: DatagramProtocol |
| 285 | |
| 286 | The base class for implementing datagram protocols (for use with |
| 287 | e.g. UDP transports). |
| 288 | |
| 289 | .. class:: SubprocessProtocol |
| 290 | |
| 291 | The base class for implementing protocols communicating with child |
| 292 | processes (through a set of unidirectional pipes). |
| 293 | |
| 294 | |
| 295 | Connection callbacks |
| 296 | -------------------- |
| 297 | |
Victor Stinner | 1538665 | 2014-06-10 09:19:26 +0200 | [diff] [blame] | 298 | These callbacks may be called on :class:`Protocol`, :class:`DatagramProtocol` |
| 299 | and :class:`SubprocessProtocol` instances: |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 300 | |
| 301 | .. method:: BaseProtocol.connection_made(transport) |
| 302 | |
| 303 | Called when a connection is made. |
| 304 | |
| 305 | The *transport* argument is the transport representing the |
| 306 | connection. You are responsible for storing it somewhere |
| 307 | (e.g. as an attribute) if you need to. |
| 308 | |
| 309 | .. method:: BaseProtocol.connection_lost(exc) |
| 310 | |
| 311 | Called when the connection is lost or closed. |
| 312 | |
| 313 | The argument is either an exception object or :const:`None`. |
| 314 | The latter means a regular EOF is received, or the connection was |
| 315 | aborted or closed by this side of the connection. |
| 316 | |
Victor Stinner | 1538665 | 2014-06-10 09:19:26 +0200 | [diff] [blame] | 317 | :meth:`~BaseProtocol.connection_made` and :meth:`~BaseProtocol.connection_lost` |
| 318 | are called exactly once per successful connection. All other callbacks will be |
| 319 | called between those two methods, which allows for easier resource management |
| 320 | in your protocol implementation. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 321 | |
| 322 | The following callbacks may be called only on :class:`SubprocessProtocol` |
| 323 | instances: |
| 324 | |
| 325 | .. method:: SubprocessProtocol.pipe_data_received(fd, data) |
| 326 | |
| 327 | Called when the child process writes data into its stdout or stderr pipe. |
| 328 | *fd* is the integer file descriptor of the pipe. *data* is a non-empty |
| 329 | bytes object containing the data. |
| 330 | |
| 331 | .. method:: SubprocessProtocol.pipe_connection_lost(fd, exc) |
| 332 | |
| 333 | Called when one of the pipes communicating with the child process |
| 334 | is closed. *fd* is the integer file descriptor that was closed. |
| 335 | |
| 336 | .. method:: SubprocessProtocol.process_exited() |
| 337 | |
| 338 | Called when the child process has exited. |
| 339 | |
| 340 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 341 | Streaming protocols |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 342 | ------------------- |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 343 | |
| 344 | The following callbacks are called on :class:`Protocol` instances: |
| 345 | |
| 346 | .. method:: Protocol.data_received(data) |
| 347 | |
| 348 | Called when some data is received. *data* is a non-empty bytes object |
| 349 | containing the incoming data. |
| 350 | |
| 351 | .. note:: |
| 352 | Whether the data is buffered, chunked or reassembled depends on |
| 353 | the transport. In general, you shouldn't rely on specific semantics |
| 354 | and instead make your parsing generic and flexible enough. However, |
| 355 | data is always received in the correct order. |
| 356 | |
| 357 | .. method:: Protocol.eof_received() |
| 358 | |
| 359 | Calls when the other end signals it won't send any more data |
| 360 | (for example by calling :meth:`write_eof`, if the other end also uses |
| 361 | asyncio). |
| 362 | |
| 363 | This method may return a false value (including None), in which case |
| 364 | the transport will close itself. Conversely, if this method returns a |
| 365 | true value, closing the transport is up to the protocol. Since the |
| 366 | default implementation returns None, it implicitly closes the connection. |
| 367 | |
| 368 | .. note:: |
| 369 | Some transports such as SSL don't support half-closed connections, |
| 370 | in which case returning true from this method will not prevent closing |
| 371 | the connection. |
| 372 | |
| 373 | :meth:`data_received` can be called an arbitrary number of times during |
| 374 | a connection. However, :meth:`eof_received` is called at most once |
| 375 | and, if called, :meth:`data_received` won't be called after it. |
| 376 | |
Victor Stinner | 54a231d | 2015-01-29 13:33:15 +0100 | [diff] [blame] | 377 | State machine: |
| 378 | |
| 379 | start -> :meth:`~BaseProtocol.connection_made` |
| 380 | [-> :meth:`~Protocol.data_received` \*] |
| 381 | [-> :meth:`~Protocol.eof_received` ?] |
| 382 | -> :meth:`~BaseProtocol.connection_lost` -> end |
| 383 | |
| 384 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 385 | Datagram protocols |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 386 | ------------------ |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 387 | |
| 388 | The following callbacks are called on :class:`DatagramProtocol` instances. |
| 389 | |
| 390 | .. method:: DatagramProtocol.datagram_received(data, addr) |
| 391 | |
| 392 | Called when a datagram is received. *data* is a bytes object containing |
| 393 | the incoming data. *addr* is the address of the peer sending the data; |
| 394 | the exact format depends on the transport. |
| 395 | |
| 396 | .. method:: DatagramProtocol.error_received(exc) |
| 397 | |
| 398 | Called when a previous send or receive operation raises an |
| 399 | :class:`OSError`. *exc* is the :class:`OSError` instance. |
| 400 | |
| 401 | This method is called in rare conditions, when the transport (e.g. UDP) |
| 402 | detects that a datagram couldn't be delivered to its recipient. |
| 403 | In many conditions though, undeliverable datagrams will be silently |
| 404 | dropped. |
| 405 | |
| 406 | |
| 407 | Flow control callbacks |
| 408 | ---------------------- |
| 409 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 410 | These callbacks may be called on :class:`Protocol`, |
| 411 | :class:`DatagramProtocol` and :class:`SubprocessProtocol` instances: |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 412 | |
| 413 | .. method:: BaseProtocol.pause_writing() |
| 414 | |
| 415 | Called when the transport's buffer goes over the high-water mark. |
| 416 | |
| 417 | .. method:: BaseProtocol.resume_writing() |
| 418 | |
| 419 | Called when the transport's buffer drains below the low-water mark. |
| 420 | |
| 421 | |
| 422 | :meth:`pause_writing` and :meth:`resume_writing` calls are paired -- |
| 423 | :meth:`pause_writing` is called once when the buffer goes strictly over |
| 424 | the high-water mark (even if subsequent writes increases the buffer size |
| 425 | even more), and eventually :meth:`resume_writing` is called once when the |
| 426 | buffer size reaches the low-water mark. |
| 427 | |
| 428 | .. note:: |
| 429 | If the buffer size equals the high-water mark, |
| 430 | :meth:`pause_writing` is not called -- it must go strictly over. |
| 431 | Conversely, :meth:`resume_writing` is called when the buffer size is |
| 432 | equal or lower than the low-water mark. These end conditions |
| 433 | are important to ensure that things go as expected when either |
| 434 | mark is zero. |
| 435 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 436 | .. note:: |
| 437 | On BSD systems (OS X, FreeBSD, etc.) flow control is not supported |
| 438 | for :class:`DatagramProtocol`, because send failures caused by |
| 439 | writing too many packets cannot be detected easily. The socket |
| 440 | always appears 'ready' and excess packets are dropped; an |
| 441 | :class:`OSError` with errno set to :const:`errno.ENOBUFS` may or |
| 442 | may not be raised; if it is raised, it will be reported to |
| 443 | :meth:`DatagramProtocol.error_received` but otherwise ignored. |
| 444 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 445 | |
Victor Stinner | 4b4f9eb | 2014-01-24 17:33:20 +0100 | [diff] [blame] | 446 | Coroutines and protocols |
| 447 | ------------------------ |
| 448 | |
| 449 | Coroutines can be scheduled in a protocol method using :func:`async`, but there |
R David Murray | 64f10d4 | 2014-11-02 12:32:26 -0500 | [diff] [blame] | 450 | is no guarantee made about the execution order. Protocols are not aware of |
| 451 | coroutines created in protocol methods and so will not wait for them. |
Victor Stinner | 4b4f9eb | 2014-01-24 17:33:20 +0100 | [diff] [blame] | 452 | |
Victor Stinner | 9592edb | 2014-02-02 15:03:02 +0100 | [diff] [blame] | 453 | To have a reliable execution order, use :ref:`stream objects <asyncio-streams>` in a |
Victor Stinner | 4b4f9eb | 2014-01-24 17:33:20 +0100 | [diff] [blame] | 454 | coroutine with ``yield from``. For example, the :meth:`StreamWriter.drain` |
| 455 | coroutine can be used to wait until the write buffer is flushed. |
| 456 | |
| 457 | |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 458 | Protocol examples |
| 459 | ================= |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 460 | |
Victor Stinner | ed05159 | 2014-10-12 20:18:16 +0200 | [diff] [blame] | 461 | .. _asyncio-tcp-echo-client-protocol: |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 462 | |
Victor Stinner | ed05159 | 2014-10-12 20:18:16 +0200 | [diff] [blame] | 463 | TCP echo client protocol |
| 464 | ------------------------ |
| 465 | |
| 466 | TCP echo client using the :meth:`BaseEventLoop.create_connection` method, send |
| 467 | data and wait until the connection is closed:: |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 468 | |
| 469 | import asyncio |
| 470 | |
Victor Stinner | cfbea3a | 2014-10-12 11:30:17 +0200 | [diff] [blame] | 471 | class EchoClientProtocol(asyncio.Protocol): |
Victor Stinner | 5366434 | 2014-10-12 11:35:09 +0200 | [diff] [blame] | 472 | def __init__(self, message, loop): |
| 473 | self.message = message |
| 474 | self.loop = loop |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 475 | |
| 476 | def connection_made(self, transport): |
Victor Stinner | 31d8322 | 2013-12-04 11:16:17 +0100 | [diff] [blame] | 477 | transport.write(self.message.encode()) |
Victor Stinner | 5366434 | 2014-10-12 11:35:09 +0200 | [diff] [blame] | 478 | print('Data sent: {!r}'.format(self.message)) |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 479 | |
| 480 | def data_received(self, data): |
Victor Stinner | 5366434 | 2014-10-12 11:35:09 +0200 | [diff] [blame] | 481 | print('Data received: {!r}'.format(data.decode())) |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 482 | |
| 483 | def connection_lost(self, exc): |
Victor Stinner | 5366434 | 2014-10-12 11:35:09 +0200 | [diff] [blame] | 484 | print('The server closed the connection') |
| 485 | print('Stop the event lop') |
| 486 | self.loop.stop() |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 487 | |
| 488 | loop = asyncio.get_event_loop() |
Victor Stinner | 5366434 | 2014-10-12 11:35:09 +0200 | [diff] [blame] | 489 | message = 'Hello World!' |
| 490 | coro = loop.create_connection(lambda: EchoClientProtocol(message, loop), |
| 491 | '127.0.0.1', 8888) |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 492 | loop.run_until_complete(coro) |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 493 | loop.run_forever() |
| 494 | loop.close() |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 495 | |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 496 | The event loop is running twice. The |
| 497 | :meth:`~BaseEventLoop.run_until_complete` method is preferred in this short |
| 498 | example to raise an exception if the server is not listening, instead of |
| 499 | having to write a short coroutine to handle the exception and stop the |
| 500 | running loop. At :meth:`~BaseEventLoop.run_until_complete` exit, the loop is |
Andrew Svetlov | 588517c | 2014-07-23 11:27:17 +0300 | [diff] [blame] | 501 | no longer running, so there is no need to stop the loop in case of an error. |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 502 | |
Victor Stinner | ed05159 | 2014-10-12 20:18:16 +0200 | [diff] [blame] | 503 | .. seealso:: |
Victor Stinner | c2721b4 | 2014-10-12 11:13:40 +0200 | [diff] [blame] | 504 | |
Victor Stinner | ed05159 | 2014-10-12 20:18:16 +0200 | [diff] [blame] | 505 | The :ref:`TCP echo client using streams <asyncio-tcp-echo-client-streams>` |
| 506 | example uses the :func:`asyncio.open_connection` function. |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 507 | |
Victor Stinner | ed05159 | 2014-10-12 20:18:16 +0200 | [diff] [blame] | 508 | |
| 509 | .. _asyncio-tcp-echo-server-protocol: |
| 510 | |
| 511 | TCP echo server protocol |
| 512 | ------------------------ |
| 513 | |
| 514 | TCP echo server using the :meth:`BaseEventLoop.create_server` method, send back |
| 515 | received data and close the connection:: |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 516 | |
| 517 | import asyncio |
| 518 | |
Victor Stinner | cfbea3a | 2014-10-12 11:30:17 +0200 | [diff] [blame] | 519 | class EchoServerClientProtocol(asyncio.Protocol): |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 520 | def connection_made(self, transport): |
| 521 | peername = transport.get_extra_info('peername') |
Victor Stinner | c2721b4 | 2014-10-12 11:13:40 +0200 | [diff] [blame] | 522 | print('Connection from {}'.format(peername)) |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 523 | self.transport = transport |
| 524 | |
| 525 | def data_received(self, data): |
Victor Stinner | c2721b4 | 2014-10-12 11:13:40 +0200 | [diff] [blame] | 526 | message = data.decode() |
| 527 | print('Data received: {!r}'.format(message)) |
| 528 | |
| 529 | print('Send: {!r}'.format(message)) |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 530 | self.transport.write(data) |
| 531 | |
Victor Stinner | 5366434 | 2014-10-12 11:35:09 +0200 | [diff] [blame] | 532 | print('Close the client socket') |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 533 | self.transport.close() |
| 534 | |
| 535 | loop = asyncio.get_event_loop() |
Victor Stinner | cfbea3a | 2014-10-12 11:30:17 +0200 | [diff] [blame] | 536 | # Each client connection will create a new protocol instance |
| 537 | coro = loop.create_server(EchoServerClientProtocol, '127.0.0.1', 8888) |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 538 | server = loop.run_until_complete(coro) |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 539 | |
Victor Stinner | ed05159 | 2014-10-12 20:18:16 +0200 | [diff] [blame] | 540 | # Serve requests until CTRL+c is pressed |
Victor Stinner | c2721b4 | 2014-10-12 11:13:40 +0200 | [diff] [blame] | 541 | print('Serving on {}'.format(server.sockets[0].getsockname())) |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 542 | try: |
| 543 | loop.run_forever() |
| 544 | except KeyboardInterrupt: |
Victor Stinner | ed05159 | 2014-10-12 20:18:16 +0200 | [diff] [blame] | 545 | pass |
Victor Stinner | c2721b4 | 2014-10-12 11:13:40 +0200 | [diff] [blame] | 546 | |
| 547 | # Close the server |
| 548 | server.close() |
| 549 | loop.run_until_complete(server.wait_closed()) |
| 550 | loop.close() |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 551 | |
R David Murray | 530a69f | 2013-12-14 11:26:06 -0500 | [diff] [blame] | 552 | :meth:`Transport.close` can be called immediately after |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 553 | :meth:`WriteTransport.write` even if data are not sent yet on the socket: both |
| 554 | methods are asynchronous. ``yield from`` is not needed because these transport |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 555 | methods are not coroutines. |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 556 | |
Victor Stinner | ed05159 | 2014-10-12 20:18:16 +0200 | [diff] [blame] | 557 | .. seealso:: |
| 558 | |
| 559 | The :ref:`TCP echo server using streams <asyncio-tcp-echo-server-streams>` |
| 560 | example uses the :func:`asyncio.start_server` function. |
| 561 | |
Victor Stinner | c7edffd | 2014-10-12 11:24:26 +0200 | [diff] [blame] | 562 | |
| 563 | .. _asyncio-udp-echo-client-protocol: |
| 564 | |
| 565 | UDP echo client protocol |
| 566 | ------------------------ |
| 567 | |
| 568 | UDP echo client using the :meth:`BaseEventLoop.create_datagram_endpoint` |
| 569 | method, send data and close the transport when we received the answer:: |
| 570 | |
| 571 | import asyncio |
| 572 | |
| 573 | class EchoClientProtocol: |
| 574 | def __init__(self, message, loop): |
| 575 | self.message = message |
| 576 | self.loop = loop |
| 577 | self.transport = None |
| 578 | |
| 579 | def connection_made(self, transport): |
| 580 | self.transport = transport |
| 581 | print('Send:', self.message) |
| 582 | self.transport.sendto(self.message.encode()) |
| 583 | |
| 584 | def datagram_received(self, data, addr): |
| 585 | print("Received:", data.decode()) |
| 586 | |
| 587 | print("Close the socket") |
| 588 | self.transport.close() |
| 589 | |
| 590 | def error_received(self, exc): |
| 591 | print('Error received:', exc) |
| 592 | |
| 593 | def connection_lost(self, exc): |
| 594 | print("Socket closed, stop the event loop") |
| 595 | loop = asyncio.get_event_loop() |
| 596 | loop.stop() |
| 597 | |
| 598 | loop = asyncio.get_event_loop() |
| 599 | message = "Hello World!" |
| 600 | connect = loop.create_datagram_endpoint( |
| 601 | lambda: EchoClientProtocol(message, loop), |
| 602 | remote_addr=('127.0.0.1', 9999)) |
| 603 | transport, protocol = loop.run_until_complete(connect) |
| 604 | loop.run_forever() |
| 605 | transport.close() |
| 606 | loop.close() |
| 607 | |
| 608 | |
| 609 | .. _asyncio-udp-echo-server-protocol: |
| 610 | |
| 611 | UDP echo server protocol |
| 612 | ------------------------ |
| 613 | |
| 614 | UDP echo server using the :meth:`BaseEventLoop.create_datagram_endpoint` |
| 615 | method, send back received data:: |
| 616 | |
| 617 | import asyncio |
| 618 | |
Victor Stinner | cfbea3a | 2014-10-12 11:30:17 +0200 | [diff] [blame] | 619 | class EchoServerProtocol: |
Victor Stinner | c7edffd | 2014-10-12 11:24:26 +0200 | [diff] [blame] | 620 | def connection_made(self, transport): |
| 621 | self.transport = transport |
| 622 | |
| 623 | def datagram_received(self, data, addr): |
| 624 | message = data.decode() |
| 625 | print('Received %r from %s' % (message, addr)) |
| 626 | print('Send %r to %s' % (message, addr)) |
| 627 | self.transport.sendto(data, addr) |
| 628 | |
| 629 | loop = asyncio.get_event_loop() |
| 630 | print("Starting UDP server") |
Victor Stinner | cfbea3a | 2014-10-12 11:30:17 +0200 | [diff] [blame] | 631 | # One protocol instance will be created to serve all client requests |
Victor Stinner | c7edffd | 2014-10-12 11:24:26 +0200 | [diff] [blame] | 632 | listen = loop.create_datagram_endpoint( |
Victor Stinner | cfbea3a | 2014-10-12 11:30:17 +0200 | [diff] [blame] | 633 | EchoServerProtocol, local_addr=('127.0.0.1', 9999)) |
Victor Stinner | c7edffd | 2014-10-12 11:24:26 +0200 | [diff] [blame] | 634 | transport, protocol = loop.run_until_complete(listen) |
| 635 | |
| 636 | try: |
| 637 | loop.run_forever() |
| 638 | except KeyboardInterrupt: |
| 639 | pass |
| 640 | |
| 641 | transport.close() |
| 642 | loop.close() |
| 643 | |
| 644 | |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 645 | .. _asyncio-register-socket: |
Victor Stinner | a881a7f | 2013-12-09 13:19:23 +0100 | [diff] [blame] | 646 | |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 647 | Register an open socket to wait for data using a protocol |
| 648 | --------------------------------------------------------- |
| 649 | |
| 650 | Wait until a socket receives data using the |
| 651 | :meth:`BaseEventLoop.create_connection` method with a protocol, and then close |
| 652 | the event loop :: |
| 653 | |
| 654 | import asyncio |
Victor Stinner | ccd8e34 | 2014-10-11 16:30:02 +0200 | [diff] [blame] | 655 | try: |
| 656 | from socket import socketpair |
| 657 | except ImportError: |
| 658 | from asyncio.windows_utils import socketpair |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 659 | |
| 660 | # Create a pair of connected sockets |
Victor Stinner | ccd8e34 | 2014-10-11 16:30:02 +0200 | [diff] [blame] | 661 | rsock, wsock = socketpair() |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 662 | loop = asyncio.get_event_loop() |
| 663 | |
| 664 | class MyProtocol(asyncio.Protocol): |
| 665 | transport = None |
| 666 | |
| 667 | def connection_made(self, transport): |
| 668 | self.transport = transport |
| 669 | |
| 670 | def data_received(self, data): |
| 671 | print("Received:", data.decode()) |
| 672 | |
| 673 | # We are done: close the transport (it will call connection_lost()) |
| 674 | self.transport.close() |
| 675 | |
| 676 | def connection_lost(self, exc): |
| 677 | # The socket has been closed, stop the event loop |
| 678 | loop.stop() |
| 679 | |
| 680 | # Register the socket to wait for data |
| 681 | connect_coro = loop.create_connection(MyProtocol, sock=rsock) |
| 682 | transport, protocol = loop.run_until_complete(connect_coro) |
| 683 | |
| 684 | # Simulate the reception of data from the network |
| 685 | loop.call_soon(wsock.send, 'abc'.encode()) |
| 686 | |
| 687 | # Run the event loop |
| 688 | loop.run_forever() |
| 689 | |
| 690 | # We are done, close sockets and the event loop |
| 691 | rsock.close() |
| 692 | wsock.close() |
| 693 | loop.close() |
| 694 | |
| 695 | .. seealso:: |
| 696 | |
| 697 | The :ref:`watch a file descriptor for read events |
| 698 | <asyncio-watch-read-event>` example uses the low-level |
| 699 | :meth:`BaseEventLoop.add_reader` method to register the file descriptor of a |
| 700 | socket. |
| 701 | |
| 702 | The :ref:`register an open socket to wait for data using streams |
| 703 | <asyncio-register-socket-streams>` example uses high-level streams |
| 704 | created by the :func:`open_connection` function in a coroutine. |