APR::Socket - Perl API for APR sockets

  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::Const::SO_NONBLOCK)) {
      $sock->opt_set(APR::Const::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::Const::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
  }

  # non-blocking io poll
  $sock->opt_set(APR::Const::SO_NONBLOCK => 1);
  my $rc = $sock->poll($c->pool, 1_000_000, APR::Const::POLLIN);
  if ($rc == APR::Const::SUCCESS) {
      # read the data
  }
  else {
      # handle the condition
  }

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

CWAPR::Socket provides the following methods: Query socket options for the specified socket

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

since: 2.0.00

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

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

ret: no return value

since: 2.0.00

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

    $rc = $sock->poll($pool, $timeout, $events);

since: 2.0.00

For example poll a non-blocking socket up to 1 second when reading data from the client:

  use APR::Socket ();
  use APR::Connection ();
  use APR::Error ();

  use APR::Const -compile => qw(SO_NONBLOCK POLLIN SUCCESS TIMEUP);

  $sock->opt_set(APR::Const::SO_NONBLOCK => 1);

  my $rc = $sock->poll($c->pool, 1_000_000, APR::Const::POLLIN);
  if ($rc == APR::Const::SUCCESS) {
      # Data is waiting on the socket to be read.
      # $sock->recv(my $buf, BUFF_LEN)
  }
  elsif ($rc == APR::Const::TIMEUP) {
      # One second elapsed and still there is no data waiting to be
      # read. for example could try again.
  }
  else {
      die "poll error: " . APR::Error::strerror($rc);
  }

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

  use APR::Status ();
  $sock->opt_set(APR::Const::SO_NONBLOCK, 1);
  # ....
  my $tries = 0;
  my $buffer;
  RETRY: my $rlen = eval { $socket->recv($buffer, SIZE) };
  if ($@)
      die $@ unless ref $@ && APR::Status::is_EAGAIN($@);
      if ($tries++ < 3) {
          # sleep 250msec
          select undef, undef, undef, 0.25;
          goto RETRY;
      }
      else {
          # do something else
      }
  }
  warn "read $rlen bytes\n"

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

  use APR::Const -compile => qw(ECONNABORTED);
  my $buffer;
  eval { $sock->recv($buffer, $wanted) };
  if ($@ == APR::Const::ECONNABORTED) {
      # ignore it or deal with it
  }

since: 2.0.00

Here is the quick prototype example, which doesn't handle any errors (mod_perl will do that for you):

  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::Const::SO_NONBLOCK)) {
      $sock->opt_set(APR::Const::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);
  }

If you want to handle errors by yourself, the loop may look like:

  use APR::Const -compile => qw(ECONNABORTED);
  # ...
  while (1) {
      my $buf;
      my $len = eval { $sock->recv($buf, $wanted) };
      if ($@) {
          # handle the error, e.g. to ignore aborted connections but
          # rethrow any other errors:
          if ($@ == APR::Const::ECONNABORTED) {
              # ignore
              last;
          }
          else {
              die $@; # retrow
          }
      }

      if ($len) {
          $sock->send($buffer);
      }
      else {
          last;
      }
  }

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

since: 2.0.00

For examples see the CWrecv item. Get socket timeout settings

  $usecs = $sock->timeout_get();

since: 2.0.00

Setup socket timeout.

  $sock->timeout_set($usecs);

t > 0

CWCIsend()CW and CWCIrecv()CW throw (CWAPR::Const::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

CWCIsend()CW and CWCIrecv()CW calls never block.

t < 0

CWCIsend()CW and CWCIrecv()CW 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

since: 2.0.00

CWAPR::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. META: Autogenerated - needs to be reviewed/completed

Bind the socket to its associated port

  $ret = $sock->bind($sa);

since: subject to change

This may be where we will find out if there is any other process using the selected port. META: Autogenerated - needs to be reviewed/completed

Close a socket.

  $ret = $sock->close();

since: subject to change

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

since: subject to change

META: Autogenerated - needs to be reviewed/completed

Listen to a bound socket for connections.

  $ret = $sock->listen($backlog);

since: subject to change

META: Autogenerated - needs to be reviewed/completed

  $ret = $from->recvfrom($sock, $flags, $buf, $len);

since: subject to change

META: Autogenerated - needs to be reviewed/completed

  $ret = $sock->sendto($where, $flags, $buf, $len);

since: subject to change

mod_perl 2.0 documentation.

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

The mod_perl development team and numerous contributors.