NAME

APR::Socket - Perl API for APR sockets

Synopsis

use APR::Socket ();

### set the socket to the blocking mode if it isn't already
### and read in the loop and echo it back
use APR::Const -compile => qw(SO_NONBLOCK);
if ($sock->opt_get(APR::SO_NONBLOCK)) {
    $sock->opt_set(APR::SO_NONBLOCK => 0);
}
# read from/write to the socket (w/o handling possible failures)
my $wanted = 1024;
while ($sock->recv(my $buff, $wanted)) {
    $sock->send($buff);
}

### get/set IO timeout and try to read some data
use APR::Const -compile => qw(TIMEUP);
# timeout is in usecs!
my $timeout = $sock->timeout_get();
if ($timeout < 10_000_000) {
    $sock->timeout_set(20_000_000); # 20 secs
}
# now read, while handling timeouts
my $wanted = 1024;
my $buff;
my $rlen = eval { $sock->recv($buff, $wanted) };
if ($@ && ref $@ && $@ == APR::TIMEUP) {
    # timeout, do something, e.g.
    warn "timed out, will try again later";
}
else {
    warn "asked for $wanted bytes, read $rlen bytes\n";
    # do something with the data
}

Description

APR::Socket provides the Perl interface to APR sockets.

API

APR::Socket provides the following methods:

`opt_get`

Query socket options for the specified socket

$val = $sock->opt_get($opt);

obj: $sock ( APR::Socket object ): the socket object to query
arg1: $opt ( APR::Const constant ): the socket option we would like to configure. Here are the available socket options.
ret: $val ( integer ): the currently set value for the socket option you've queried for
excpt: APR::Error
since: 1.99_14

Examples can be found in the socket options constants section. For example setting the IO to the blocking mode.

`opt_set`

Setup socket options for the specified socket

$sock->opt_set($opt, $val);

obj: $sock ( APR::Socket object object ): the socket object to set up.
arg1: $opt ( APR::Const constant ): the socket option we would like to configure. Here are the available socket options.
arg2: $val ( integer ): value for the option. Refer to the socket options section to learn about the expected values.
ret: no return value
excpt: APR::Error
since: 1.99_14

Examples can be found in the socket options constants section. For example setting the IO to the blocking mode.

`recv`

Read incoming data from the socket

$len = $sock->recv($buffer, $wanted);

obj: $sock ( APR::SockAddr object object )

The socket to read from

arg1: $buffer ( SCALAR )

The buffer to fill. All previous data will be lost.

arg2: $wanted ( int )

How many bytes to attempt to read.

ret: $len ( number )

How many bytes were actually read.

$buffer gets populated with the string that is read. It will contain an empty string if there was nothing to read.

excpt: APR::Error

If you get the '(11) Resource temporarily unavailable' error (exception APR::EAGAIN), then you didn't ensure that the socket is in a blocking IO mode before using it.

If timeout was set via timeout_set|/C_timeout_set_, you may need to catch the APR::TIMEUP exception. For example:

use APR::Const -compile => qw(TIMEUP);
my $buffer;
eval { $sock->recv($buffer, $wanted) };
if ($@ && $@ == APR::TIMEUP) {
    # timeout, do something, e.g.
}

since: 1.99_14

Examples:

use APR::Socket ();

# set the socket to the blocking mode if it isn't already
use APR::Const -compile => qw(SO_NONBLOCK);
if ($sock->opt_get(APR::SO_NONBLOCK)) {
    $sock->opt_set(APR::SO_NONBLOCK => 0);
}
# read from/write to the socket (w/o handling possible failures)
my $wanted = 1024;
while ($sock->recv(my $buffer, $wanted)) {
    $sock->send($buffer);
}

`send`

Write data to the socket

$wlen = $sock->send($buf, $opt_len);

obj: $sock ( APR::Socket object ): The socket to write to
arg1: $buf ( scalar ): The data to send
opt arg2: $opt_len ( int ): There is no need to pass this argument, unless you want to send less data than contained in $buf.
ret: $wlen ( integer ): How many bytes were sent
since: 1.99_14

For examples see the recv item.

`timeout_get`

Get socket timeout settings

$usecs = $sock->timeout_get();

obj: $sock ( APR::Socket object ): The socket to set up.
ret: $usecs ( number): Currently set timeout in microseconds (and also the blocking IO behavior). See (APR::timeout_set) for possible values and their meaning.
excpt: APR::Error
since: 1.99_14

`timeout_set`

Setup socket timeout.

$sock->timeout_set($usecs);

obj: $sock ( APR::Socket object )

The socket to set up.

arg1: $usecs ( number )

Value for the timeout in microseconds and also the blocking IO behavior.

The possible values are:

t > 0

send() and recv() throw (APR::TIMEUP exception) if specified time elapses with no data sent or received.

Notice that the positive value is in micro seconds. So if you want to set the timeout for 5 seconds, the value should be: 5_000_000.

This mode sets the socket into a non-blocking IO mode.

t == 0

send() and recv() calls never block.

t < 0

send() and recv() calls block.

Usually just -1 is used for this case, but any negative value will do.

This mode sets the socket into a blocking IO mode.

ret: no return value

excpt: APR::Error

since: 1.99_14

Unsupported API

APR::Socket also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.