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 (1) {
      # read from the socket
      my $buff = $sock->recv($wanted);
      my $rlen = length $buff;
      last if $rlen == 0; # EOF
  
      # write to the socket
      my $wlen = $sock->send($buff);
      last if $wlen != $rlen; # shouldn't happen
  }

  ### 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 = eval { $sock->recv($wanted) };
  if ($@ && ref $@ && $@ == APR::TIMEUP) {
      # timeout, do something, e.g.
      warn "timed out, will try again later";
  }
  else {
      my $rlen = length $buff;
      warn "asked for $wanted bytes, read $rlen bytes\n";
  }

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 ): 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

  my $buff = $sock->recv($wanted);

obj: $sock ( APR::SockAddr object )

The socket to read from

arg1: $wanted ( int )

How many bytes to attempt to read.

ret: $buf ( string )

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

excpt: APR::Error

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

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

since: 1.99_14

Examples:

  use APR::Socket ();
  my $wanted = 1024;
  while (1) {
      # read from the socket
      my $buff = $sock->recv($wanted);
      my $rlen = length $buff;
      last if $rlen == 0; # EOF
  
      # write to the socket
      my $wlen = $sock->send($buff);
      last if $wlen != $rlen; # shouldn't happen
  }

`send`

Write data to the socket

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

obj: $sock ( APR::Socket ): 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 ): 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 )

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 eachother take the steps necessary to shift the method to an officially supported API.