You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by st...@apache.org on 2004/05/08 03:29:26 UTC
cvs commit: modperl-docs/src/docs/2.0/api/APR Socket.pod
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