[Patch] Improve IO::Socket::connected() documentation #14199
Created by firstname.lastname@example.org
Attached doc patch for IO::Socket::connected() is the eventual disposition of
It is essentially identical to the suggested wording posted here:
the only differences being some minor wordsmithing.
From 1b346f7bfbfcf3107b3b89c8208bf0bf00ac0840 Mon Sep 17 00:00:00 2001 From: "Glenn D. Golden" <email@example.com> Date: Tue, 28 Oct 2014 04:24:04 -0600 Subject: [PATCH] Improve connected() doc --- dist/IO/lib/IO/Socket.pm | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/dist/IO/lib/IO/Socket.pm b/dist/IO/lib/IO/Socket.pm index 625c71a..c98ea0b 100644 --- a/dist/IO/lib/IO/Socket.pm +++ b/dist/IO/lib/IO/Socket.pm @@ -499,8 +499,23 @@ C<use> declaration will fail at compile time. =item connected -If the socket is in a connected state the peer address is returned. -If the socket is not in a connected state then undef will be returned. +If the socket is in a connected state, the peer address is returned. If the +socket is not in a connected state, undef is returned. + +Note that connected() considers a half-open TCP socket to be "in a connected +state". Specifically, connected() does not distinguish between the +B<ESTABLISHED> and B<CLOSE-WAIT> TCP states; it returns the peer address, +rather than undef, in either case. Thus, in general, connected() cannot +be used to reliably learn whether the peer has initiated a graceful shutdown +because in most cases (see below) the local TCP state machine remains in +B<CLOSE-WAIT> until the local application calls shutdown() or close(); +only at that point does connected() return undef. + +The "in most cases" hedge is because local TCP state machine behavior may +depend on the peer's socket options. In particular, if the peer socket has +SO_LINGER enabled with a zero timeout, then the peer's close() will generate +a RST segment, upon receipt of which the local TCP transitions immediately to +B<CLOSED>, and in that state, connected() I<will> return undef. =item protocol -- 2.1.3
On Sat Nov 01 10:20:26 2014, firstname.lastname@example.org wrote:
Thanks, applied as 7eb3f2c.