Inconsistent documentation of socket backlog

[ellen364]

Documentation

The documentation inconsistently describes when a default value is chosen for socket backlog.

Paragraph for socket.listen says "if not specified, a default reasonable value is chosen."

Paragraph for socket.create_server says "when 0 a default reasonable value is chosen."

Calling socket.create_server without passing a backlog argument calls socket.listen without backlog argument. CPython does try to pick a sensible backlog value.

cpython/Lib/socket.py

Lines 936 to 939 in 53a54b7

	if backlog is None:
	sock.listen()
	else:
	sock.listen(backlog)

cpython/Modules/socketmodule.c

Line 3564 in 53a54b7

int backlog = Py_MIN(SOMAXCONN, 128);

The behaviour is different when backlog=0. In that case, it seems the C implementation may pick a value. See, for example, https://pubs.opengroup.org/onlinepubs/009696799/functions/listen.html

Simplest fix is probably making the socket.create_server docs consistent with socket.listen: "if not specified, a default reasonable value is chosen". That would, however, ignore the backlog=0 behaviour and might prove surprising.

Linked PRs

• [3.11] gh-96773 Fix documentation of socket backlog (GH-96778) #100661
• [3.10] gh-96773 Fix documentation of socket backlog (GH-96778) #100662