perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/api/APR Socket.pod
Date Wed, 08 Sep 2004 00:44:38 GMT
stas        2004/09/07 17:44:38

  Modified:    src/docs/2.0/api/APR Socket.pod
  Log:
  new api: poll()
  Submitted by:	Ken Simpson <ksimpson@larch.mailchannels.com>
  
  Revision  Changes    Path
  1.13      +131 -2    modperl-docs/src/docs/2.0/api/APR/Socket.pod
  
  Index: Socket.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/APR/Socket.pod,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -u -r1.12 -r1.13
  --- Socket.pod	18 Aug 2004 01:39:32 -0000	1.12
  +++ Socket.pod	8 Sep 2004 00:44:38 -0000	1.13
  @@ -41,6 +41,17 @@
         # do something with the data
     }
   
  +  # non-blocking io poll
  +  $sock->opt_set(APR::SO_NONBLOCK => 1);
  +  my $rc = $sock->poll($c->pool, 1_000_000, APR::POLLIN);
  +  if ($rc == APR::SUCCESS) {
  +      # read the data
  +  }
  +  else {
  +      # handle the condition
  +  }
  +
  +
   
   =head1 Description
   
  @@ -140,6 +151,84 @@
   
   
   
  +=head2 C<poll>
  +
  +Poll the socket for events:
  +
  +    $rc = $sock->poll($pool, $timeout, $events);
  +
  +=over 4
  +
  +=item obj: C<$sock>
  +( C<L<APR::Socket object|docs::2.0::api::APR::Socket>> )
  +
  +The socket to poll
  +
  +=item arg1: C<$pool>
  +( C<L<APR::Pool object|docs::2.0::api::APR::Pool>> )
  +
  +usually C<L<$c-E<gt>pool|docs::2.0::api::Apache::Connection/C_pool_>>.
  +
  +=item arg2: C<$timeout> ( integer )
  +
  +The amount of time to wait (in milliseconds) for the specified events
  +to occur.
  +
  +=item arg3: C<$events> ( C<L<APR::Const :poll
  +constants|docs::2.0::api::APR::Const/C__poll_>> )
  +
  +The events for which to wait.
  +
  +For example use
  +C<L<APR::POLLIN|docs::2.0::api::APR::Const/C_APR__POLLIN_>> to wait
  +for incoming data to be available,
  +C<L<APR::POLLOUT|docs::2.0::api::APR::Const/C_APR__POLLOUT_>> to wait
  +until it's possible to write data to the socket and
  +C<L<APR::POLLPRI|docs::2.0::api::APR::Const/C_APR__POLLPRI_>> to wait
  +for priority data to become available.
  +
  +=item ret: C<$rc>
  +( C<L<APR::Const constant|docs::2.0::api::APR::Const>> )
  +
  +If C<APR::SUCCESS> is received than the polling was successful. If not
  +-- the error code is returned, which can be converted to the error
  +string with help of
  +C<L<APR::Error::strerror|docs::2.0::api::APR::Error/C_strerror_>>.
  +
  +=item since: 1.99_17
  +
  +=back
  +
  +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::SO_NONBLOCK => 1);
  +  
  +  my $rc = $sock->poll($c->pool, 1_000_000, APR::POLLIN);
  +  if ($rc == APR::SUCCESS) {
  +      # Data is waiting on the socket to be read.
  +      # $sock->recv(my $buf, BUFF_LEN)
  +  }
  +  elsif ($rc == APR::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);
  +  }
  +
  +
  +
  +
  +
  +
  +
   
   
   =head2 C<recv>
  @@ -189,11 +278,27 @@
         # timeout, do something, e.g.
     }
   
  +If not handled -- you may get the error C<'70007: The timeout
  +specified has expired'>.
  +
  +Another error condition that may occur is the C<'(104) Connection
  +reset by peer'> error, which is up to your application logic to decide
  +whether it's an error or not. This error usually happens when the
  +client aborts the connection.
  +
  +  use APR::Const -compile => qw(ECONNABORTED);
  +  my $buffer;
  +  eval { $sock->recv($buffer, $wanted) };
  +  if ($@ == APR::ECONNABORTED) {
  +      # ignore it or deal with it
  +  }
  +
   =item since: 1.99_14
   
   =back
   
  -Examples:
  +Here is the quick prototype example, which doesn't handle any errors
  +(mod_perl will do that for you):
   
     use APR::Socket ();
     
  @@ -208,8 +313,32 @@
         $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::ECONNABORTED) {
  +              # ignore
  +              last;
  +          }
  +          else {
  +              die $@; # retrow
  +          }
  +      }
  +  
  +      if ($len) {
  +          $sock->send($buffer);
  +      }
  +      else {
  +          last;
  +      }
  +  }
   
   
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message