APR::Socket - Perl API for APR sockets


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.

bind

META: Autogenerated - needs to be reviewed/completed

Bind the socket to its associated port

  $ret = $sock->bind($sa);
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )
The socket to bind

arg1: $sa ( APR::SockAddr object|docs::2.0::api::APR::SockAddr )
The socket address to bind to

ret: $ret ( integer )
since: subject to change

This may be where we will find out if there is any other process using the selected port.

close

META: Autogenerated - needs to be reviewed/completed

Close a socket.

  $ret = $sock->close();
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )
The socket to close

ret: $ret ( integer )
since: subject to change

connect

META: Autogenerated - needs to be reviewed/completed

Issue a connection request to a socket either on the same machine or a different one.

  $ret = $sock->connect($sa);
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )
The socket we wish to use for our side of the connection

arg1: $sa ( APR::SockAddr object|docs::2.0::api::APR::SockAdrr )
The address of the machine we wish to connect to. If NULL, APR assumes that the sockaddr_in in the apr_socket is completely filled out.

ret: $ret ( integer )
since: subject to change

listen

META: Autogenerated - needs to be reviewed/completed

Listen to a bound socket for connections.

  $ret = $sock->listen($backlog);
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )
The socket to listen on

arg1: $backlog ( integer )
The number of outstanding connections allowed in the sockets listen queue. If this value is less than zero, the listen queue size is set to zero.

ret: $ret ( integer )
since: subject to change

recvfrom

META: Autogenerated - needs to be reviewed/completed

  $ret = $from->recvfrom($sock, $flags, $buf, $len);
obj: $from ( APR::SockAddr object|docs::2.0::api::APR::SockAddr )
The apr_sockaddr_t to fill in the recipient info

arg1: $sock ( APR::SockAddr object|docs::2.0::api::APR::SockAddr )
The socket to use

arg2: $flags ( integer )
The flags to use

arg3: $buf ( integer )
The buffer to use

arg4: $len ( string )
The length of the available buffer

ret: $ret ( integer )
since: subject to change

sendto

META: Autogenerated - needs to be reviewed/completed

  $ret = $sock->sendto($where, $flags, $buf, $len);
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )
The socket to send from

arg1: $where ( APR::Socket object|docs::2.0::api::APR::Socket )
The apr_sockaddr_t describing where to send the data

arg2: $flags ( integer )
The flags to use

arg3: $buf ( scalar )
The data to send

arg4: $len ( string )
The length of the data to send

ret: $ret ( integer )
since: subject to change


See Also

mod_perl 2.0 documentation.


Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.


Authors

The mod_perl development team and numerous contributors.

 APR::Socket - Perl API for APR sockets