add description and caveats

1 files changed, 36 insertions, 0 deletions

diff --git a/lib/IO/Socket/Telnet/HalfDuplex.pm b/lib/IO/Socket/Telnet/HalfDuplex.pm
index 5b82130..4cd7c0c 100644
--- a/lib/IO/Socket/Telnet/HalfDuplex.pm
+++ b/lib/IO/Socket/Telnet/HalfDuplex.pm
@@ -18,6 +18,35 @@ IO::Socket::Telnet::HalfDuplex - more reliable telnet communication
 
 =head1 DESCRIPTION
 
+A common issue when communicating over a network is deciding when input is done
+being received. If the communication is a fixed protocol, the protocol should
+define this clearly, but this isn't always the case; in particular, interactive
+telnet sessions provide no way to tell whether or not the data that has been
+sent is the full amount of data that the server wants to send, or whether that
+was just a single packet which should be combined with future packets to form
+the full message. This module attempts to alleviate this somewhat by providing
+a way to estimate how much time you should wait before assuming that all the
+data has arrived.
+
+The method used is a slight abuse of the telnet out-of-band option
+negotiation - most telnet servers, when told to DO an option that they don't
+understand, will respond that they WONT do that option, and will continue to do
+so every time (this is not guaranteed by the telnet spec, however - if this
+isn't the case, L<IO::Socket::Telnet> is the only option). We can use this
+method to get an estimate of how long we should wait for the data. This module
+sends a ping in the out-of-band data before reading, with the assumption that
+by the time it gets to the server, all the output that has been generated by
+your most recent C<send> will already be queued up in the server's output
+buffer. This would be guaranteed if we were just communicating with the telnet
+server directly, but typically we are communicating with a subprocess spawned
+by the telnet server, which means that the telnet server can respond to the
+ping while the subprocess is continuing to send data, making this not failsafe.
+It's generally a safe assumption for interactive programs across a network,
+though, since interactive programs tend to respond quickly, relative to network
+latency. After sending the ping, we just read as much as we can until we get
+the pong. This process is all wrapped up in the L</read> method provided by
+this module; the rest of the interface is just inherited from
+L<IO::Socket::Telnet>.
 
 =cut
 
@@ -99,6 +128,13 @@ sub _telnet_negotiation {
     return $self->$external_callback($option);
 }
 
+=head1 CAVEATS
+
+This is not actually guaranteed half-duplex communication - that's not possible
+in general over a telnet connection without specifying a protocol in advance.
+This module just does its best to get as close as possible, and tends to do
+reasonably well in practice.
+
 =head1 BUGS
 
 No known bugs.