Skip to content

Commit

Permalink
GH-88968: Add notes about socket ownership transfers (GH-97936)
Browse files Browse the repository at this point in the history
(cherry picked from commit 74ea204)

Co-authored-by: Guido van Rossum <[email protected]>
  • Loading branch information
miss-islington and gvanrossum authored Oct 5, 2022
1 parent 6f23472 commit c80c282
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 0 deletions.
24 changes: 24 additions & 0 deletions Doc/library/asyncio-eventloop.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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*.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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).

Expand Down Expand Up @@ -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.

Expand Down
24 changes: 24 additions & 0 deletions Doc/library/asyncio-stream.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -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
Expand Down

0 comments on commit c80c282

Please sign in to comment.