[Twisted-Python] Effects of backlog parameter on listenTCP

[Tim Allen]

On Wed, Jul 18, 2012 at 04:43:01PM -0700, Tobias Oberstein wrote:
> Could someone shortly elaborate on the semantics / effect of the parameter "backlog" with listenTCP?

It exactly corresponds to the "backlog" parameter of the BSD socket API
function "listen(int sockfd, int backlog)". On my Debian Testing
machine, the listen(2) manpage says:

    The backlog argument defines the maximum length to which the queue
    of pending connections for sockfd may grow. If a connection request
    arrives when the queue is full, the client may receive an error with
    an indication of ECONNREFUSED or, if the underlying protocol
    supports retransmission, the request may be ignored so that a later
    reattempt at connection succeeds.

..and later:

    The behavior of the backlog argument on TCP sockets changed with
    Linux 2.2. Now it specifies the queue length for completely
    established sockets waiting to be accepted, instead of the number of
    incomplete connection requests.  The maximum length of the queue for
    incomplete sockets can be set using
    /proc/sys/net/ipv4/tcp_max_syn_backlog.  When syncookies are enabled
    there is no logical maximum length and this setting is ignored. See
    tcp(7) for more information.

    If the backlog argument is greater than the value in
    /proc/sys/net/core/somaxconn, then it is silently truncated to that
    value; the default value in this file is 128. In kernels before
    2.4.25, this limit was a hard coded value, SOMAXCONN, with the value
    128.

Obviously the Twisted documentation can't go into all this detail
because Twisted runs on more operating systems than just Linux. Every OS
that supports the BSD socket API should have documentation explaining
the precise definition and meaning of the backlog parameter on that
platform. For example, here's the MSDN docs for the listen() function in
WinSock:

http://msdn.microsoft.com/en-us/library/windows/desktop/ms739168%28v=vs.85%29.aspx