Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IO::Socket::Timeout(3)User Contributed Perl DocumentatioIO::Socket::Timeout(3)

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.

perl v5.32.1			  2015-09-29		IO::Socket::Timeout(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CLASS METHOD | METHODS | WHEN TIMEOUT IS HIT | IF YOU NEED TO RETRY | IMPORT options | ENVIRONMENT VARIABLE | SEE ALSO | THANKS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IO::Socket::Timeout&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help