[Python-checkins] GH-88968: Add notes about socket ownership transfers (GH-97936)
miss-islington
webhook-mailer at python.org
Wed Oct 5 19:54:51 EDT 2022
https://github.com/python/cpython/commit/c80c282d112b9771fc9ac652095c76cfdad9ace3
commit: c80c282d112b9771fc9ac652095c76cfdad9ace3
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-10-05T16:54:46-07:00
summary:
GH-88968: Add notes about socket ownership transfers (GH-97936)
(cherry picked from commit 74ea204634f8eb4745afd5cb75c3fe7749cf38b5)
Co-authored-by: Guido van Rossum <guido at python.org>
files:
M Doc/library/asyncio-eventloop.rst
M Doc/library/asyncio-stream.rst
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index d2f786990802..343672d350ab 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -450,6 +450,12 @@ Opening network connections
*happy_eyeballs_delay*, *interleave*
and *local_addr* should be specified.
+ .. note::
+
+ The *sock* argument transfers ownership of the socket to the
+ transport created. To close the socket, call the transport's
+ :meth:`~asyncio.BaseTransport.close` method.
+
* *local_addr*, if given, is a ``(local_host, local_port)`` tuple used
to bind the socket locally. The *local_host* and *local_port*
are looked up using ``getaddrinfo()``, similarly to *host* and *port*.
@@ -555,6 +561,12 @@ Opening network connections
transport. If specified, *local_addr* and *remote_addr* should be omitted
(must be :const:`None`).
+ .. note::
+
+ The *sock* argument transfers ownership of the socket to the
+ transport created. To close the socket, call the transport's
+ :meth:`~asyncio.BaseTransport.close` method.
+
See :ref:`UDP echo client protocol <asyncio-udp-echo-client-protocol>` and
:ref:`UDP echo server protocol <asyncio-udp-echo-server-protocol>` examples.
@@ -644,6 +656,12 @@ Creating network servers
* *sock* can optionally be specified in order to use a preexisting
socket object. If specified, *host* and *port* must not be specified.
+ .. note::
+
+ The *sock* argument transfers ownership of the socket to the
+ server created. To close the socket, call the server's
+ :meth:`~asyncio.Server.close` method.
+
* *backlog* is the maximum number of queued connections passed to
:meth:`~socket.socket.listen` (defaults to 100).
@@ -729,6 +747,12 @@ Creating network servers
* *sock* is a preexisting socket object returned from
:meth:`socket.accept <socket.socket.accept>`.
+ .. note::
+
+ The *sock* argument transfers ownership of the socket to the
+ transport created. To close the socket, call the transport's
+ :meth:`~asyncio.BaseTransport.close` method.
+
* *ssl* can be set to an :class:`~ssl.SSLContext` to enable SSL over
the accepted connections.
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 65f3d5322db2..19210a556057 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -67,6 +67,12 @@ and work with streams:
The rest of the arguments are passed directly to
:meth:`loop.create_connection`.
+ .. note::
+
+ The *sock* argument transfers ownership of the socket to the
+ :class:`StreamWriter` created. To close the socket, call its
+ :meth:`~asyncio.StreamWriter.close` method.
+
.. versionchanged:: 3.7
Added the *ssl_handshake_timeout* parameter.
@@ -103,6 +109,12 @@ and work with streams:
The rest of the arguments are passed directly to
:meth:`loop.create_server`.
+ .. note::
+
+ The *sock* argument transfers ownership of the socket to the
+ server created. To close the socket, call the server's
+ :meth:`~asyncio.Server.close` method.
+
.. versionchanged:: 3.7
Added the *ssl_handshake_timeout* and *start_serving* parameters.
@@ -123,6 +135,12 @@ and work with streams:
See also the documentation of :meth:`loop.create_unix_connection`.
+ .. note::
+
+ The *sock* argument transfers ownership of the socket to the
+ :class:`StreamWriter` created. To close the socket, call its
+ :meth:`~asyncio.StreamWriter.close` method.
+
.. availability:: Unix.
.. versionchanged:: 3.7
@@ -143,6 +161,12 @@ and work with streams:
See also the documentation of :meth:`loop.create_unix_server`.
+ .. note::
+
+ The *sock* argument transfers ownership of the socket to the
+ server created. To close the socket, call the server's
+ :meth:`~asyncio.Server.close` method.
+
.. availability:: Unix.
.. versionchanged:: 3.7
More information about the Python-checkins
mailing list