1IO::Socket::Timeout(3pmU)ser Contributed Perl DocumentatiIoOn::Socket::Timeout(3pm)
2
3
4

NAME

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

VERSION

9       version 0.32
10

SYNOPSIS

12         use IO::Socket::Timeout;
13
14         # creates a standard IO::Socket::INET object, with a connection timeout
15         my $socket = IO::Socket::INET->new( Timeout => 2 );
16         # enable read and write timeouts on the socket
17         IO::Socket::Timeout->enable_timeouts_on($socket);
18         # setup the timeouts
19         $socket->read_timeout(0.5);
20         $socket->write_timeout(0.5);
21
22         # When using the socket:
23         use Errno qw(ETIMEDOUT EWOULDBLOCK);
24         print $socket "some request";
25         my $response = <$socket>;
26         if (! $response && ( 0+$! == ETIMEDOUT || 0+$! == EWOULDBLOCK )) {
27           die "timeout reading on the socket";
28         }
29

DESCRIPTION

31       "IO::Socket" provides a way to set a timeout on the socket, but the
32       timeout will be used only for connection, not for reading / writing
33       operations.
34
35       This module provides a way to set a timeout on read / write operations
36       on an "IO::Socket" instance, or any "IO::Socket::*" modules, like
37       "IO::Socket::INET".
38

CLASS METHOD

40   enable_timeouts_on
41         IO::Socket::Timeout->enable_timeouts_on($socket);
42
43       Given a socket, it'll return it, but will enable read and write
44       timeouts on it.  You'll have to use "read_timeout" and "write_timeout"
45       on it later on.
46
47       Returns the socket, so that you can chain this method with others.
48
49       If the argument is "undef", the method simply returns empty list.
50

METHODS

52       These methods are to be called on a socket that has been previously
53       passed to "enable_timeouts_on()".
54
55   read_timeout
56         my $current_timeout = $socket->read_timeout();
57         $socket->read_timeout($new_timeout);
58
59       Get or set the read timeout value for a socket created with this
60       module.
61
62   write_timeout
63         my $current_timeout = $socket->write_timeout();
64         $socket->write_timeout($new_timeout);
65
66       Get or set the write timeout value for a socket created with this
67       module.
68
69   disable_timeout
70         $socket->disable_timeout;
71
72       Disable the read and write timeouts for a socket created with this
73       module.
74
75   enable_timeout
76         $socket->enable_timeout;
77
78       Re-enable the read and write timeouts for a socket created with this
79       module.
80
81   timeout_enabled
82         my $is_timeout_enabled = $socket->timeout_enabled();
83         $socket->timeout_enabled(0);
84
85       Get or Set the fact that a socket has timeouts enabled.
86

WHEN TIMEOUT IS HIT

88       When a timeout (read, write) is hit on the socket, the function trying
89       to be performed will return "undef" or empty string, and $! will be set
90       to "ETIMEOUT" or "EWOULDBLOCK". You should test for both.
91
92       You can import "ETIMEOUT" and "EWOULDBLOCK" by using "POSIX":
93
94         use Errno qw(ETIMEDOUT EWOULDBLOCK);
95

IF YOU NEED TO RETRY

97       If you want to implement a try / wait / retry mechanism, I recommend
98       using a third-party module, like "Action::Retry". Something like this:
99
100         my $socket;
101
102         my $action = Action::Retry->new(
103           attempt_code => sub {
104               # (re-)create the socket if needed
105               if (! $socket) {
106                 $socket = IO::Socket->new(...);
107                 IO::Socket::Timeout->enable_timeouts_on($socket);
108                 $socket->read_timeout(0.5);
109               }
110               # send the request, read the answer
111               $socket->print($_[0]);
112               defined(my $answer = $socket->getline)
113                 or $socket = undef, die $!;
114               $answer;
115           },
116           on_failure_code => sub { die 'aborting, to many retries' },
117         );
118
119         my $reply = $action->run('GET mykey');
120

IMPORT options

122       You can give a list of socket modules names when use-ing this module,
123       so that internally, composed classes needed gets created and loaded at
124       compile time.
125
126         use IO::Socket::Timeout qw(IO::Socket::INET);
127

ENVIRONMENT VARIABLE

129   PERL_IO_SOCKET_TIMEOUT_FORCE_SELECT
130       This module implements timeouts using one of two strategies. If
131       possible (if the operating system is linux, freebsd or mac), it uses
132       "setsockopt()" to set read / write timeouts. Otherwise it uses
133       "select()" before performing socket operations.
134
135       To force the use of "select()", you can set
136       PERL_IO_SOCKET_TIMEOUT_FORCE_SELECT to a true value at compile time
137       (typically in a BEGIN block)
138

SEE ALSO

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

THANKS

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

AUTHOR

147       Damien "dams" Krotkine
148

150       This software is copyright (c) 2013 by Damien "dams" Krotkine.
151
152       This is free software; you can redistribute it and/or modify it under
153       the same terms as the Perl 5 programming language system itself.
154
155
156
157perl v5.34.0                      2021-07-22          IO::Socket::Timeout(3pm)
Impressum