stas 2004/06/09 09:17:43
Modified: src/docs/2.0/api/APR Brigade.pod Bucket.pod Error.pod
Socket.pod
src/docs/2.0/user/handlers filters.pod http.pod
protocols.pod
Log:
sync with API changes
Revision Changes Path
1.9 +21 -9 modperl-docs/src/docs/2.0/api/APR/Brigade.pod
Index: Brigade.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/APR/Brigade.pod,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -u -r1.8 -r1.9
--- Brigade.pod 4 Jun 2004 06:40:36 -0000 1.8
+++ Brigade.pod 9 Jun 2004 16:17:42 -0000 1.9
@@ -24,8 +24,8 @@
$bb2 = APR::Brigade->new($r->pool, $c->bucket_alloc);
$bb1->concat($bb2);
- $data = $bb->flatten();
- $data2 = $bb2->flatten($len);
+ $len = $bb->flatten($data);
+ $len = $bb2->flatten($data, $wanted);
$len = $bb->length;
$bb3 = $bb->split($b_last);
@@ -204,22 +204,34 @@
Get the data from buckets in the bucket brigade as one string
- $data = $bb->flatten();
- $data = $bb->flatten($len);
+ $len = $bb->flatten($buffer);
+ $len = $bb->flatten($buffer, $wanted);
=over 4
=item obj: C<$bb>
( C<L<APR::Brigade object|docs::2.0::api::APR::Brigade>> )
-=item opt arg1: C<$len> ( number )
+=item arg1: C<$buffer> ( SCALAR )
-If no argument is passed then all data will be returned. If C<$len> is
-specified -- that number or less bytes will be returned.
+The buffer to fill. All previous data will be lost.
-=item ret: C<$data> ( string )
+=item opt arg2: C<$wanted> ( number )
-=item since: 1.99_10
+If no argument is passed then all data will be returned. If C<$wanted>
+is specified -- that number or less bytes will be returned.
+
+=item ret: C<$len> ( number )
+
+How many bytes were actually read.
+
+C<$buffer> gets populated with the string that is read. It will
+contain an empty string if there was nothing to read.
+
+
+=item since: 1.99_15
+
+=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>
=back
1.7 +19 -10 modperl-docs/src/docs/2.0/api/APR/Bucket.pod
Index: Bucket.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/APR/Bucket.pod,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -u -r1.6 -r1.7
--- Bucket.pod 4 Jun 2004 09:30:52 -0000 1.6
+++ Bucket.pod 9 Jun 2004 16:17:42 -0000 1.7
@@ -16,8 +16,8 @@
$b2->is_eos;
$b3->is_flush;
- $len = $b1->length;
- $data = $b1->read;
+ $len = $b1->length;
+ $len = $b1->read($data);
$type = $b1->type;
$b1->insert_after($b2);
@@ -332,8 +332,8 @@
Read the data from the bucket.
- $data = $b->read();
- $data = $b->read($block);
+ $len = $b->read($buffer,);
+ $len = $b->read($buffer, $block);
=over 4
@@ -342,7 +342,11 @@
The bucket to read from
-=item opt arg1: C<$block> ( C<L<APR::Const :read_type
+=item arg1: C<$buffer> ( SCALAR )
+
+The buffer to fill. All previous data will be lost.
+
+=item opt arg2: C<$block> ( C<L<APR::Const :read_type
constant|docs::2.0::api::APR::Const/C__read_type_>> )
optional reading mode constant.
@@ -350,10 +354,12 @@
By default the read is blocking, via C<L<APR::BLOCK_READ
constant|docs::2.0::api::APR::Const/C_APR__BLOCK_READ_>>.
-=item ret: C<$data> ( string )
+=item ret: C<$len> ( number )
+
+How many bytes were actually read
-the read data buffer. The buffer will contain an empty string if no
-data was read.
+C<$buffer> gets populated with the string that is read. It will
+contain an empty string if there was nothing to read.
=item since: 1.99_15
@@ -365,12 +371,15 @@
Blocking read:
- my $data = $b->read();
+ my $len = $b->read(my $buffer);
Non-blocking read:
use APR::Const -compile 'NONBLOCK_READ';
- my $data = $b->read(APR::NONBLOCK_READ);
+ my $len = $b->read(my $buffer, APR::NONBLOCK_READ);
+
+
+
1.6 +4 -4 modperl-docs/src/docs/2.0/api/APR/Error.pod
Index: Error.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/APR/Error.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -u -r1.5 -r1.6
--- Error.pod 3 Jun 2004 08:42:23 -0000 1.5
+++ Error.pod 9 Jun 2004 16:17:42 -0000 1.6
@@ -89,8 +89,7 @@
For example you wrote a code that performs L<a socket
read|docs::2.0::api::APR::Socket/C_recv_>:
- my $buff = $sock->recv(1024);
- my $rlen = length $buff;
+ my $rlen = $sock->recv(my $buff, 1024);
warn "read $rlen bytes\n";
and in certain cases it times out. The code will die and log the
@@ -99,12 +98,13 @@
you rewrite the code to handle the exception like so:
use APR::Const -compile => qw(TIMEUP);
- my $buff = eval { $sock->recv(1024) };
+ my $buff;
+ retry:
+ my $rlen = eval { $sock->recv($buff, 1024) };
if ($@) {
die $@ unless ref $@ && $@ == APR::TIMEUP;
goto retry;
}
- my $rlen = length $buff;
warn "read $rlen bytes\n";
Notice that we handle non-object and non-C<APR::Error> exceptions as
1.10 +20 -26 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.9
retrieving revision 1.10
diff -u -u -r1.9 -r1.10
--- Socket.pod 25 May 2004 02:04:15 -0000 1.9
+++ Socket.pod 9 Jun 2004 16:17:42 -0000 1.10
@@ -17,15 +17,8 @@
}
# 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
+ while ($sock->recv(my $buff, $wanted)) {
+ $sock->send($buff);
}
### get/set IO timeout and try to read some data
@@ -37,14 +30,15 @@
}
# now read, while handling timeouts
my $wanted = 1024;
- my $buff = eval { $sock->recv($wanted) };
+ 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 {
- my $rlen = length $buff;
warn "asked for $wanted bytes, read $rlen bytes\n";
+ # do something with the data
}
@@ -152,7 +146,7 @@
Read incoming data from the socket
- my $buff = $sock->recv($wanted);
+ $len = $sock->recv($buffer, $wanted);
=over 4
@@ -161,14 +155,20 @@
The socket to read from
-=item arg1: C<$wanted> ( int )
+=item arg1: C<$buffer> ( SCALAR )
+
+The buffer to fill. All previous data will be lost.
+
+=item arg2: C<$wanted> ( int )
How many bytes to attempt to read.
-=item ret: C<$buf> ( string )
+=item ret: C<$len> ( number )
-C<$buf> gets populated with the string that is read. It will contain
-an empty string if there is nothing to read.
+How many bytes were actually read.
+
+C<$buffer> gets populated with the string that is read. It will
+contain an empty string if there was nothing to read.
=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>
@@ -183,7 +183,8 @@
exception. For example:
use APR::Const -compile => qw(TIMEUP);
- my $buff = eval { $sock->recv($wanted) };
+ my $buffer;
+ eval { $sock->recv($buffer, $wanted) };
if ($@ && $@ == APR::TIMEUP) {
# timeout, do something, e.g.
}
@@ -203,15 +204,8 @@
}
# 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
+ while ($sock->recv(my $buffer, $wanted)) {
+ $sock->send($buffer);
}
1.44 +10 -11 modperl-docs/src/docs/2.0/user/handlers/filters.pod
Index: filters.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/filters.pod,v
retrieving revision 1.43
retrieving revision 1.44
diff -u -u -r1.43 -r1.44
--- filters.pod 6 Jun 2004 10:11:44 -0000 1.43
+++ filters.pod 9 Jun 2004 16:17:42 -0000 1.44
@@ -1162,8 +1162,8 @@
last;
}
- my $buf = $b->read;
- $data .= $buf if length $buf;
+ $b->read(my $data);
+ $data .= $buf;
}
} while (!$seen_eos);
@@ -1245,7 +1245,8 @@
my @data;
for (my $b = $bb->first; $b; $b = $bb->next($b)) {
- push @data, $b->type->name, $b->read;
+ $b->read(my $bdata);
+ push @data, $b->type->name, $bdata;
}
# send the sniffed info to STDERR so not to interfere with normal
@@ -1531,7 +1532,7 @@
return $rv unless $rv == APR::SUCCESS;
for (my $b = $bb->first; $b; $b = $bb->next($b)) {
- my $data = $b->read;
+ $b->read(my $data);
warn("data: $data\n");
if ($data and $data =~ s|^GET|HEAD|) {
@@ -1770,8 +1771,8 @@
last;
}
- my $data = $b->read;
- $b = APR::Bucket->new(lc $data) if length $data;
+ my $len = $b->read(my $data);
+ $b = APR::Bucket->new(lc $data) if $len;
$bb->insert_tail($b);
}
@@ -2120,8 +2121,7 @@
last;
}
- my $data = $bucket->read;
- if (length $data) {
+ if ($bucket->read(my $data)) {
$data = join "",
map {scalar(reverse $_), "\n"} split "\n", $data;
$bucket = APR::Bucket->new($data);
@@ -2318,7 +2318,7 @@
last;
}
- my $buf = $b->read;
+ $b->read(my $buf);
warn "DATA bucket: [$buf]\n" if $debug;
push @data, $buf;
}
@@ -2413,8 +2413,7 @@
my @data;
for (my $b = $bb->first; $b; $b = $bb->next($b)) {
$seen_eos++, last if $b->is_eos;
- my $bdata = $b->read;
- $bdata = '' unless defined $bdata;
+ $b->read(my $bdata);
push @data, $bdata;
}
return (join('', @data), $seen_eos);
1.34 +13 -2 modperl-docs/src/docs/2.0/user/handlers/http.pod
Index: http.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -u -r1.33 -r1.34
--- http.pod 6 Jun 2004 10:11:44 -0000 1.33
+++ http.pod 9 Jun 2004 16:17:42 -0000 1.34
@@ -315,6 +315,17 @@
=head2 PerlMapToStorageHandler
+The I<map_to_storage> phase is used to perform the translation of a
+
+
+
+
+request's URI into an corresponding filename. If no custom handler is
+provided, the server's standard translation rules (e.g., C<Alias>
+directives, mod_rewrite, etc.) will continue to be used. A
+C<PerlTransHandler> handler can alter the default translation
+mechanism or completely override it.
+
META: add something here
This phase is of type
@@ -446,8 +457,8 @@
last;
}
- my $buf = $b->read;
- $data .= $buf if length $buf;
+ $b->read(my $buf);
+ $data .= $buf;
}
} while (!$seen_eos);
1.23 +8 -17 modperl-docs/src/docs/2.0/user/handlers/protocols.pod
Index: protocols.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/protocols.pod,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -u -r1.22 -r1.23
--- protocols.pod 4 Jun 2004 06:40:16 -0000 1.22
+++ protocols.pod 9 Jun 2004 16:17:42 -0000 1.23
@@ -247,16 +247,9 @@
# set the socket to the blocking mode
$sock->opt_set(APR::SO_NONBLOCK => 0);
- while (1) {
- # read from the socket
- my $buff = $sock->recv(BUFF_LEN);
- my $rlen = length $buff;
- last if $rlen == 0; # EOF
+ while ($sock->recv(my $buff, BUFF_LEN)) {
last if $buff =~ /^[\r\n]+$/;
-
- # write to the socket
- my $wlen = $sock->send($buff);
- last if $wlen != $rlen; # shouldn't happen
+ $sock->send($buff);
}
Apache::OK;
@@ -276,10 +269,9 @@
Inside the recv/send loop, the handler attempts to read C<BUFF_LEN>
bytes from the client socket into the C<$buff> buffer. The handler
-breaks the loop if the returned buffer is empty, (there was nothing
-more to read (EOF)) or if the buffer contains nothing but new line
-character(s), which is how we know to abort the connection in the
-interactive mode.
+breaks the loop if nothing was read (EOF) or if the buffer contains
+nothing but new line character(s), which is how we know to abort the
+connection in the interactive mode.
If the handler receives some data, it sends it unmodified back to the
client with the C<APR::Socket::send()> method. When the loop is
@@ -378,8 +370,7 @@
last;
}
- my $data = $bucket->read;
- if (length $data) {
+ if ($bucket->read(my $data)) {
$last++ if $data =~ /^[\r\n]+$/;
# could do some transformation on data here
$bucket = APR::Bucket->new($data);
@@ -421,7 +412,7 @@
while ($bb_in = get_brigade()) {
while ($bucket_in = $bb_in->get_bucket()) {
- my $data = $bucket_in->read();
+ $bucket_in->read(my $data);
# do something with data
$bucket_out = new_bucket($data);
@@ -542,7 +533,7 @@
last;
}
- my $data = $bb->flatten;
+ next unless $bb->flatten(my $data);
$bb->cleanup;
last if $data =~ /^[\r\n]+$/;
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
