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 Sat, 08 May 2004 01:29:26 GMT
stas        2004/05/07 18:29:26

  Modified:    src/docs/2.0/api/APR Socket.pod
  Log:
  sync update, add missing entries
  
  Revision  Changes    Path
  1.3       +364 -111  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.2
  retrieving revision 1.3
  diff -u -u -r1.2 -r1.3
  --- Socket.pod	8 Apr 2004 21:25:25 -0000	1.2
  +++ Socket.pod	8 May 2004 01:29:26 -0000	1.3
  @@ -1,6 +1,6 @@
   =head1 NAME
   
  -APR::Socket - Perl API for XXX
  +APR::Socket - Perl API for APR sockets
   
   
   
  @@ -8,22 +8,370 @@
   =head1 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";
  +  }
   
  -META: to be completed
   
  +=head1 Description
   
  +C<APR::Socket> provides the Perl interface to APR sockets.
   
   
  -=head1 Description
   
  -META: to be completed
   
  +=head1 API
   
  +C<APR::Socket> provides the following methods:
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +=head2 C<opt_get>
  +
  +Query socket options for the specified socket
  +
  +  $val = $sock->opt_get($opt);
  +
  +=over 4
  +
  +=item arg1: C<$sock>
  +( C<L<APR::Socket object|docs::2.0::api::APR::Socket>> )
  +
  +the socket object to query
  +
  +=item arg2: C<$opt>
  +( C<L<APR::Const constant|docs::2.0::api::APR::Const/C__socket_>> )
  +
  +the socket option we would like to configure.  Here are the
  +L<available socket options|docs::2.0::api::APR::Const/C__socket_>.
  +
  +=item ret: C<$val> ( integer )
  +
  +the currently set value for L<the socket
  +option|docs::2.0::api::APR::Const/C__socket_> you've queried for
  +
  +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>
  +
  +=item since: 1.99_14
  +
  +=back
  +
  +Examples can be found in L<the socket options constants
  +section|docs::2.0::api::APR::Const/C__socket_>. For example L<setting 
  +the IO to the blocking
  +mode|docs::2.0::api::APR::Const/C_APR__SO_NONBLOCK_>.
  +
  +
  +
  +
  +=head2 C<opt_set>
  +
  +Setup socket options for the specified socket
  +
  +  $sock->opt_set($opt, $val);
  +
  +=over 4
  +
  +=item arg1: C<$sock>
  +( C<L<APR::Socket|docs::2.0::api::APR::Socket>> object )
  +
  +the socket object to set up.
  +
  +=item arg2: C<$opt>
  +( C<L<APR::Const|docs::2.0::api::APR::Const/C__socket_>> constant )
  +
  +the socket option we would like to configure.  Here are the
  +L<available socket options|docs::2.0::api::APR::Const/C__socket_>.
  +
  +=item arg3: C<$val> ( integer )
  +
  +value for the option. Refer to the L<socket
  +options|docs::2.0::api::APR::Const/C__socket_> section to learn about
  +the expected values.
  +
  +=item ret: no return value
  +
  +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>
  +
  +=item since: 1.99_14
  +
  +=back
  +
  +Examples can be found in L<the socket options constants
  +section|docs::2.0::api::APR::Const/C__socket_>. For example L<setting 
  +the IO to the blocking
  +mode|docs::2.0::api::APR::Const/C_APR__SO_NONBLOCK_>.
  +
  +
  +
  +
  +
  +=head2 C<recv>
  +
  +Read incoming data from the socket
  +
  +  my $buff = $sock->recv($wanted);
  +
  +=over 4
  +
  +=item arg1: C<$sock>
  +( C<L<APR::SockAddr|docs::2.0::api::APR::SockAddr>> object )
  +
  +The socket to read from
  +
  +=item arg2: C<$wanted> ( int )
  +
  +How many bytes to attempt to read.
  +
  +=item ret: C<$buf> ( string )
  +
  +C<$buf> gets populated with the string that is read. It will contain
  +an empty string if there is nothing to read.
  +
  +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>
  +
  +If timeout was set via C<timeout_set|/C_timeout_set_>, you may need to
  +catch C<L<APR::TIMEUP|docs::2.0::api::APR::Const/C_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.
  +  }
  +
  +=item since: 1.99_14
  +
  +=back
  +
  +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
  +  }
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +=head2 C<send>
  +
  +Write data to the socket
  +
  +  $wlen = $sock->send($buf, $opt_len);
  +
  +=over 4
  +
  +=item arg1: C<$sock> ( C<L<APR::Socket|docs::2.0::api::APR::Socket>>
)
  +
  +The socket to write to
  +
  +=item arg2: C<$buf> ( scalar )
  +
  +The data to send
  +
  +=item opt arg3: C<$opt_len> ( int )
  +
  +There is no need to pass this argument, unless you want to send less
  +data than contained in C<$buf>.
  +
  +=item ret: C<$wlen> ( integer )
  +
  +How many bytes were sent
  +
  +=item since: 1.99_14
  +
  +=back
  +
  +For examples see the C<L<recv|/C_recv_>> item.
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +=head2 C<timeout_get>
  +
  +Get socket timeout settings
  +
  +  $usecs = $sock->timeout_get();
  +
  +=over 4
  +
  +=item arg1: C<$sock> ( C<L<APR::Socket|docs::2.0::api::APR::Socket>>
)
  +
  +The socket to set up.
  +
  +=item ret: C<$usecs> ( number)
  +
  +Currently set timeout in microseconds (and also the blocking IO
  +behavior). See (C<L<APR::timeout_set|/C__timeout_set_>>) for possible
  +values and their meaning.
  +
  +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>
  +
  +=item since: 1.99_14
  +
  +=back
   
   
  -=head1 API
   
  -C<APR::Socket> provides the following functions and/or methods:
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +=head2 C<timeout_set>
  +
  +Setup socket timeout.
  +
  +  $sock->timeout_set($usecs);
  +
  +=over 4
  +
  +=item arg1: C<$sock> ( C<L<APR::Socket|docs::2.0::api::APR::Socket>>
)
  +
  +The socket to set up.
  +
  +=item arg2: C<$usecs> ( number )
  +
  +Value for the timeout in microseconds and also the blocking IO
  +behavior.
  +
  +The possible values are:
  +
  +=over
  +
  +=item t E<gt> 0
  +
  +C<L<send()|/C__send_>> and C<L<recv()|/C__recv_)>> throw
  +(C<L<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.
  +
  +=item t == 0
  +
  +C<L<send()|/C__send_>> and C<L<recv()|/C__recv_)>> calls never
block.
  +
  +=item t E<lt> 0
  +
  +C<L<send()|/C__send_>> and C<L<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.
  +
  +=item ret: no return value
  +
  +=back
  +
  +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>
  +
  +=item since: 1.99_14
  +
  +=back
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +=head1 Unsupported API
  +
  +C<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 added later as a
  +need arises. If you need any of these methods please contact L<the
  +mod_perl development mailing list|maillist::dev>, present your case,
  +showing us some sample code and we will take care of adding the new
  +method.
  +
   
   
   
  @@ -48,7 +396,7 @@
   
   =item ret: C<$ret> (integer)
   
  -
  +=item since: subject to change
   
   =back
   
  @@ -57,6 +405,9 @@
   
   
   
  +
  +
  +
   =head2 C<close>
   
   META: Autogenerated - needs to be reviewed/completed
  @@ -74,6 +425,8 @@
   =item ret: C<$ret> (integer)
   
   
  +=item since: subject to change
  +
   
   =back
   
  @@ -104,6 +457,7 @@
   
   =item ret: C<$ret> (integer)
   
  +=item since: subject to change
   
   
   =back
  @@ -134,6 +488,7 @@
   
   =item ret: C<$ret> (integer)
   
  +=item since: subject to change
   
   
   =back
  @@ -142,81 +497,7 @@
   
   
   
  -=head2 C<opt_get>
   
  -Query socket options for the specified socket
  -
  -  $val = $sock->opt_get($opt);
  -  die "failed to \$sock->opt_get: $ARP::err" unless defined $val;
  -
  -=over 4
  -
  -=item arg1: C<$sock> (C<L<APR::Socket|docs::2.0::api::APR::Socket>>)
  -
  -The socket object to query
  -
  -=item arg2: C<$opt>
  -(C<L<APR::Const|docs::2.0::api::APR::Const/C__socket_>> constant)
  -
  -The socket option we would like to configure.  Here are the
  -L<available socket options|docs::2.0::api::APR::Const/C__socket_>.
  -
  -=item ret: C<$val> (integer)
  -
  -If a defined value is returned, it's the currently set value.
  -
  -If C<undef> is returned, the operation has failed, check C<$ARP::err>
  -for the error message.
  -
  -=item since: 1.99_14
  -
  -=back
  -
  -Examples can be found in L<the socket options constants
  -section|docs::2.0::api::APR::Const/C__socket_>.
  -
  -
  -
  -
  -
  -=head2 C<opt_set>
  -
  -Setup socket options for the specified socket
  -
  -  $oldval = $sock->opt_set($opt, $val);
  -  die "failed to \$sock->opt_set: $ARP::err" unless defined $oldval;
  -
  -=over 4
  -
  -=item arg1: C<$sock> (C<L<APR::Socket|docs::2.0::api::APR::Socket>>)
  -
  -The socket object to set up.
  -
  -=item arg2: C<$opt>
  -(C<L<APR::Const|docs::2.0::api::APR::Const/C__socket_>> constant)
  -
  -The socket option we would like to configure.  Here are the
  -L<available socket options|docs::2.0::api::APR::Const/C__socket_>.
  -
  -=item arg3: C<$val> (integer)
  -
  -Value for the option. Refer to the L<socket
  -options|docs::2.0::api::APR::Const/C__socket_> section to learn about
  -the expected values.
  -
  -=item ret: C<$oldval> (integer)
  -
  -If a defined value is returned, it's the previously set value.
  -
  -If C<undef> is returned, the operation has failed, check C<$ARP::err>
  -for the error message.
  -
  -=item since: 1.99_14
  -
  -=back
  -
  -Examples can be found in L<the socket options constants
  -section|docs::2.0::api::APR::Const/C__socket_>.
   
   
   
  @@ -253,6 +534,7 @@
   
   =item ret: C<$ret> (integer)
   
  +=item since: subject to change
   
   
   =back
  @@ -293,42 +575,13 @@
   
   =item ret: C<$ret> (integer)
   
  -
  +=item since: subject to change
   
   =back
   
   
   
   
  -
  -=head2 C<timeout_set>
  -
  -META: Autogenerated - needs to be reviewed/completed
  -
  -Setup socket timeout for the specified socket
  -
  -  $ret = $sock->timeout_set($t);
  -
  -=over 4
  -
  -=item arg1: C<$sock> (C<L<APR::Socket|docs::2.0::api::APR::Socket>>)
  -
  -The socket to set up.
  -
  -=item arg2: C<$t> (number)
  -
  -Value for the timeout:
  -
  -   t > 0  -- read and write calls return APR::TIMEUP if specified time
  -             elapsess with no data read or written
  -   t == 0 -- read and write calls never block
  -   t < 0  -- read and write calls block
  -
  -=item ret: C<$ret> (integer)
  -
  -
  -
  -=back
   
   
   
  
  
  

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