Damien Krotkine > IO-Socket-Timeout-0.27 > IO::Socket::Timeout

Download:
IO-Socket-Timeout-0.27.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.27   Source  

NAME ^

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

VERSION ^

version 0.27

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 strategy. If possible (if the operating system is linux 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.

syntax highlighting: