NAME

       IO::Socket::Timeout - IO::Socket with read/write timeout

VERSION

       version 0.32

SYNOPSIS

         use IO::Socket::Timeout;

         # creates a standard IO::Socket::INET object, with a connection timeout
         my $socket = IO::Socket::INET->new( Timeout => 2 );
         # enable read and write timeouts on the socket
         IO::Socket::Timeout->enable_timeouts_on($socket);
         # setup the timeouts
         $socket->read_timeout(0.5);
         $socket->write_timeout(0.5);

         # When using the socket:
         use Errno qw(ETIMEDOUT EWOULDBLOCK);
         print $socket "some request";
         my $response = <$socket>;
         if (! $response && ( 0+$! == ETIMEDOUT || 0+$! == EWOULDBLOCK )) {
           die "timeout reading on the socket";
         }

DESCRIPTION

       "IO::Socket" provides a way to set a timeout on the socket, but the timeout will be used
       only for connection, not for reading / writing operations.

       This module provides a way to set a timeout on read / write operations on an "IO::Socket"
       instance, or any "IO::Socket::*" modules, like "IO::Socket::INET".

CLASS METHOD

   enable_timeouts_on
         IO::Socket::Timeout->enable_timeouts_on($socket);

       Given a socket, it'll return it, but will enable read and write timeouts on it.  You'll
       have to use "read_timeout" and "write_timeout" on it later on.

       Returns the socket, so that you can chain this method with others.

       If the argument is "undef", the method simply returns empty list.

METHODS

       These methods are to be called on a socket that has been previously passed to
       "enable_timeouts_on()".

   read_timeout
         my $current_timeout = $socket->read_timeout();
         $socket->read_timeout($new_timeout);

       Get or set the read timeout value for a socket created with this module.

   write_timeout
         my $current_timeout = $socket->write_timeout();
         $socket->write_timeout($new_timeout);

       Get or set the write timeout value for a socket created with this module.

   disable_timeout
         $socket->disable_timeout;

       Disable the read and write timeouts for a socket created with this module.

   enable_timeout
         $socket->enable_timeout;

       Re-enable the read and write timeouts for a socket created with this module.

   timeout_enabled
         my $is_timeout_enabled = $socket->timeout_enabled();
         $socket->timeout_enabled(0);

       Get or Set the fact that a socket has timeouts enabled.

WHEN TIMEOUT IS HIT

       When a timeout (read, write) is hit on the socket, the function trying to be performed
       will return "undef" or empty string, and $! will be set to "ETIMEOUT" or "EWOULDBLOCK".
       You should test for both.

       You can import "ETIMEOUT" and "EWOULDBLOCK" by using "POSIX":

         use Errno qw(ETIMEDOUT EWOULDBLOCK);

IF YOU NEED TO RETRY

       If you want to implement a try / wait / retry mechanism, I recommend using a third-party
       module, like "Action::Retry". Something like this:

         my $socket;

         my $action = Action::Retry->new(
           attempt_code => sub {
               # (re-)create the socket if needed
               if (! $socket) {
                 $socket = IO::Socket->new(...);
                 IO::Socket::Timeout->enable_timeouts_on($socket);
                 $socket->read_timeout(0.5);
               }
               # send the request, read the answer
               $socket->print($_[0]);
               defined(my $answer = $socket->getline)
                 or $socket = undef, die $!;
               $answer;
           },
           on_failure_code => sub { die 'aborting, to many retries' },
         );

         my $reply = $action->run('GET mykey');

IMPORT options

       You can give a list of socket modules names when use-ing this module, so that internally,
       composed classes needed gets created and loaded at compile time.

         use IO::Socket::Timeout qw(IO::Socket::INET);

ENVIRONMENT VARIABLE

   PERL_IO_SOCKET_TIMEOUT_FORCE_SELECT
       This module implements timeouts using one of two strategies. If possible (if the operating
       system is linux, freebsd or mac), it uses "setsockopt()" to set read / write timeouts.
       Otherwise it uses "select()" before performing socket operations.

       To force the use of "select()", you can set PERL_IO_SOCKET_TIMEOUT_FORCE_SELECT to a true
       value at compile time (typically in a BEGIN block)

SEE ALSO

       Action::Retry, IO::Select, PerlIO::via::Timeout, Time::Out

THANKS

       Thanks to Vincent Pitt, Christian Hansen and Toby Inkster for various help and useful
       remarks.

AUTHOR

       Damien "dams" Krotkine

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013 by Damien "dams" Krotkine.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.