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