APR::Socket - Perl API for APR sockets

Unsupported API

See Also
Copyright
Authors

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|docs::2.0::api::APR::Socket ): the socket object to query
arg1: $opt ( APR::Const constant|docs::2.0::api::APR::Const/C__socket_ ): 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|docs::2.0::api::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|docs::2.0::api::APR::Socket object ): the socket object to set up.
arg1: $opt ( APR::Const|docs::2.0::api::APR::Const/C__socket_ 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|docs::2.0::api::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|docs::2.0::api::APR::SockAddr 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|docs::2.0::api::APR::Error

If you get the '(11) Resource temporarily unavailable' error (exception APR::EAGAIN|docs::2.0::api::APR::Const/C_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|docs::2.0::api::APR::Const/C_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|docs::2.0::api::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|/C_recv_ item.

`timeout_get`

Get socket timeout settings

  $usecs = $sock->timeout_get();

obj: $sock ( APR::Socket object|docs::2.0::api::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|/C__timeout_set_) for possible values and their meaning.
excpt: APR::Error|docs::2.0::api::APR::Error
since: 1.99_14

`timeout_set`

Setup socket timeout.

  $sock->timeout_set($usecs);

obj: $sock ( APR::Socket object|docs::2.0::api::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()|/C__send_ and recv()|/C__recv_) throw (APR::TIMEUP|docs::2.0::api::APR::Const/C__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()|/C__send_ and recv()|/C__recv_) calls never block.

t < 0

send()|/C__send_ and recv()|/C__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|docs::2.0::api::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.