---
name: "IO::Socket::Timeout"
section: "3pm"
platform: "linux"
package: "libio-socket-timeout-perl"
version: "0.32-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/IO::Socket::Timeout"
---

# IO::Socket::Timeout(3pm)

IO::Socket with read/write timeout

## 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.