From docspaulpearson@example.org Fri Jul 02 16:51:25 2004 Return-Path: <docspaulpearson@example.org> Delivered-To: paulpearson@example.org Received: (qmail 79954 invoked from network); 2 Jul 2004 16:51:25 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (83.161.120.155) by minotaur-2.apache.org with SMTP; 2 Jul 2004 16:51:25 -0000 Received: (qmail 25063 invoked by uid 500); 2 Jul 2004 16:51:34 -0000 Delivered-To: paulpearson@example.org Received: (qmail 24971 invoked by uid 500); 2 Jul 2004 16:51:30 -0000 Mailing-List: contact paulpearson@example.org; run by ezmlm Precedence: bulk Reply-To: paulpearson@example.org List-Post: <mailto:paulpearson@example.org> List-Help: <mailto:paulpearson@example.org> List-Unsubscribe: <mailto:paulpearson@example.org> List-Subscribe: <mailto:paulpearson@example.org> Delivered-To: mailing list paulpearson@example.org Received: (qmail 24930 invoked by uid 500); 2 Jul 2004 16:51:29 -0000 Delivered-To: paulpearson@example.org X-ASF-Spam-Status: No, hits=0.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Date: 2 Jul 2004 16:51:18 -0000 Message-ID: <paulpearson@example.org> From: paulpearson@example.org To: paulpearson@example.org Subject: cvs commit: modperl-docs/src/docs/2.0/api/APR PerlIO.pod X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N stas 2004/07/02 09:51:18 Modified: src/docs/2.0/api/APR PerlIO.pod Log: rework the prerequisites section Revision Changes Path 1.9 +21 -6 modperl-docs/src/docs/2.0/api/APR/PerlIO.pod Index: PerlIO.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/APR/PerlIO.pod,v retrieving revision 1.8 retrieving revision 1.9 diff -u -u -r1.8 -r1.9 --- PerlIO.pod 22 May 2004 02:03:26 -0000 1.8 +++ PerlIO.pod 2 Jul 2004 16:51:18 -0000 1.9 @@ -41,24 +41,39 @@ to APR. But you can use APR Perl IO directly if you want. +=head1 Prerequisites +Not every Perl will have full C<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PerlIO> functionality available. +Before using the Perl IO APR layer one has to check whether it's +supported by the used APR/Perl build. Perl 5.8.x or higher with perlio +enabled is required. You can check whether your Perl fits the bill by +running: -=head1 Constants - - + % perl -V:useperlio + useperlio='define'; -=head2 APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PerlIO888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PERLIO_LAYERS_ARE_ENABLED +It should say I<define>. -Before using the Perl IO APR layer one has to check whether it's -supported by the used APR/Perl build. +If you need to do the checking in the code, there is a special +constant provided by C<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PerlIO>, which can be used as follows: + use APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PerlIO (); die "This Perl build doesn't support PerlIO layers" unless APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PerlIO888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PERLIO_LAYERS_ARE_ENABLED; Notice that loading C<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PerlIO> won't fail when Perl IO layers aren't available since C<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PerlIO> provides functionality for Perl builds not supporting Perl IO layers. + + +=head1 Constants + + + +=head2 C<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PerlIO888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PERLIO_LAYERS_ARE_ENABLED> + +See L<Prerequisites|/Prerequisites>. --------------------------------------------------------------------- To unsubscribe, e-mail: paulpearson@example.org For additional commands, e-mail: paulpearson@example.org From docspaulpearson@example.org Fri Jul 02 23:17:12 2004 Return-Path: <docspaulpearson@example.org> Delivered-To: paulpearson@example.org Received: (qmail 25602 invoked from network); 2 Jul 2004 23:17:12 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (83.161.120.155) by minotaur-2.apache.org with SMTP; 2 Jul 2004 23:17:12 -0000 Received: (qmail 18691 invoked by uid 500); 2 Jul 2004 23:17:27 -0000 Delivered-To: paulpearson@example.org Received: (qmail 18621 invoked by uid 500); 2 Jul 2004 23:17:25 -0000 Mailing-List: contact paulpearson@example.org; run by ezmlm Precedence: bulk Reply-To: paulpearson@example.org List-Post: <mailto:paulpearson@example.org> List-Help: <mailto:paulpearson@example.org> List-Unsubscribe: <mailto:paulpearson@example.org> List-Subscribe: <mailto:paulpearson@example.org> Delivered-To: mailing list paulpearson@example.org Received: (qmail 18548 invoked by uid 500); 2 Jul 2004 23:17:23 -0000 Delivered-To: paulpearson@example.org X-ASF-Spam-Status: No, hits=0.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Date: 2 Jul 2004 23:17:05 -0000 Message-ID: <paulpearson@example.org> From: paulpearson@example.org To: paulpearson@example.org Subject: cvs commit: modperl-docs/src/docs/2.0/api/Apache Filter.pod X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N stas 2004/07/02 16:17:05 Modified: src/docs/2.0/api/Apache Filter.pod Log: polish Revision Changes Path 1.18 +3 -3 modperl-docs/src/docs/2.0/api/Apache/Filter.pod Index: Filter.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Filter.pod,v retrieving revision 1.17 retrieving revision 1.18 diff -u -u -r1.17 -r1.18 --- Filter.pod 19 Jun 2004 20:07:47 -0000 1.17 +++ Filter.pod 2 Jul 2004 23:17:05 -0000 1.18 @@ -346,7 +346,7 @@ =item excpt: C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror>> -Exceptions are thrown only when this function is called in the void +Exceptions are thrown only when this function is called in the VOID context. Refer to the C<L<get_brigade()|/C_get_brigade_>> entry for details. @@ -477,7 +477,7 @@ =item excpt: C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror>> You don't have to ask for the return value. If this function is called -in the void context, e.g.: +in the VOID context, e.g.: $f->next->get_brigade($bb, $mode, $block, $readbytes); @@ -634,7 +634,7 @@ =item excpt: C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror>> -Exceptions are thrown only when this function is called in the void +Exceptions are thrown only when this function is called in the VOID context. Refer to the C<L<get_brigade()|/C_get_brigade_>> entry for details. --------------------------------------------------------------------- To unsubscribe, e-mail: paulpearson@example.org For additional commands, e-mail: paulpearson@example.org From docspaulpearson@example.org Fri Jul 02 23:18:01 2004 Return-Path: <docspaulpearson@example.org> Delivered-To: paulpearson@example.org Received: (qmail 25759 invoked from network); 2 Jul 2004 23:18:01 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (83.161.120.155) by minotaur-2.apache.org with SMTP; 2 Jul 2004 23:18:01 -0000 Received: (qmail 22246 invoked by uid 500); 2 Jul 2004 23:18:15 -0000 Delivered-To: paulpearson@example.org Received: (qmail 22146 invoked by uid 500); 2 Jul 2004 23:18:13 -0000 Mailing-List: contact paulpearson@example.org; run by ezmlm Precedence: bulk Reply-To: paulpearson@example.org List-Post: <mailto:paulpearson@example.org> List-Help: <mailto:paulpearson@example.org> List-Unsubscribe: <mailto:paulpearson@example.org> List-Subscribe: <mailto:paulpearson@example.org> Delivered-To: mailing list paulpearson@example.org Received: (qmail 22092 invoked by uid 500); 2 Jul 2004 23:18:12 -0000 Delivered-To: paulpearson@example.org X-ASF-Spam-Status: No, hits=0.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Date: 2 Jul 2004 23:17:53 -0000 Message-ID: <paulpearson@example.org> From: paulpearson@example.org To: paulpearson@example.org Subject: cvs commit: modperl-docs/src/docs/2.0/user/porting compat.pod X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N stas 2004/07/02 16:17:53 Modified: src/docs/2.0/api/Apache RequestIO.pod src/docs/2.0/user/porting compat.pod Log: complete Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestIO Revision Changes Path 1.5 +294 -141 modperl-docs/src/docs/2.0/api/Apache/RequestIO.pod Index: RequestIO.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/RequestIO.pod,v retrieving revision 1.4 retrieving revision 1.5 diff -u -u -r1.4 -r1.5 --- RequestIO.pod 22 May 2004 02:03:27 -0000 1.4 +++ RequestIO.pod 2 Jul 2004 23:17:53 -0000 1.5 @@ -8,8 +8,20 @@ =head1 Synopsis use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestIO (); - -META: to be completed + + $rc = $r->discard_request_body(); + + $r->print("foo", "bar"); + $r->puts("foo", "bar"); # same as print, but no flushing + $r->printf("%s $d", "foo", 5); + + $r->read($buffer, $len); + + $r->rflush(); + + $r->sendfile($filename); + + $r->write("foobartarcar", 3, 5); @@ -31,112 +43,142 @@ =head2 C<discard_request_body> -META: Autogenerated - needs to be reviewed/completed - In HTTP/1.1, any method can have a body. However, most GET handlers wouldn't know what to do with a request body if they received one. -This helper routine tests for and reads any message body in the request, -simply discarding whatever it receives. We need to do this because -failing to read the request body would cause it to be interpreted -as the next request on a persistent connection. +This helper routine tests for and reads any message body in the +request, simply discarding whatever it receives. We need to do this +because failing to read the request body would cause it to be +interpreted as the next request on a persistent connection. - $ret = $r->discard_request_body(); + $rc = $r->discard_request_body(); =over 4 -=item obj: C<$r> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) +=item obj: C<$r> +( C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>> ) The current request -=item ret: C<$ret> (integer) +=item ret: C<$rc> ( integer ) -error status if request is malformed, Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK otherwise +C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst status constant|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst>> if request +is malformed, C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK> otherwise. + +=item since: 1.99_10 =back +Since we return an error status if the request is malformed, this +routine should be called at the beginning of a no-body handler, e.g., + use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const -compile => qw(OK); + $rc = $r->discard_request_body; + return $rc if $rc != Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK; -=head2 C<setup_client_block> -META: Autogenerated - needs to be reviewed/completed -META: I think this method is deprecated along with other client_block -methods, use plain $r-E<lt>read() instead. +=head2 C<print> -Setup the client to allow Apache to read the request body. +Send data to the client. - $ret = $r->setup_client_block($read_policy); + $cnt = $r->print(@msg); =over 4 -=item obj: C<$r> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) +=item obj: C<$r> +( C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>> ) -The current request +=item arg1: C<@msg> ( ARRAY ) -=item arg1: C<$read_policy> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) +Data to send -How the server should interpret a chunked transfer-encoding. One of: +=item ret: C<$cnt> ( number ) - REQUEST_NO_BODY Send 413 error if message has any body - REQUEST_CHUNKED_ERROR Send 411 error if body without Content-Length - REQUEST_CHUNKED_DECHUNK If chunked, remove the chunks for me. +How many bytes were sent (or buffered) -=item ret: C<$ret> (integer) +=item excpt: C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror>> -either OK or an error code +=item since: 1.99_10 =back +The data is flushed only if STDOUT stream's C<$|> is true. Otherwise +it's buffered up to the size of the buffer, flushing only excessive +data. -=head2 C<should_client_block> +=head2 C<printf> -META: Autogenerated - needs to be reviewed/completed +Format and send data to the client (same as C<printf>). -META: I think this method is deprecated along with other client_block -methods, use plain $r-E<lt>read() instead. + $cnt = $r->printf($format, @args); -Determine if the client has sent any data. This also sends a -100 Continue response to HTTP/1.1 clients, so modules should not be called -until the module is ready to read content. +=over 4 - $ret = $r->should_client_block(); +=item obj: C<$r> +( C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>> ) -=over 4 +=item arg1: C<$format> ( string ) -=item obj: C<$r> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) +Format string, as in the Perl core C<printf> function. -The current request +=item arg2: C<@args> ( ARRAY ) + +Arguments to be formatted, as in the Perl core C<printf> function. -=item ret: C<$ret> (integer) +=item ret: C<$cnt> ( number ) -0 if there is no message to read, 1 otherwise +How many bytes were sent (or buffered) + +=item excpt: C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror>> + +=item since: 1.99_10 =back +The data is flushed only if STDOUT stream's C<$|> is true. Otherwise +it's buffered up to the size of the buffer, flushing only excessive +data. -=head2 C<print> -Send data to the client. +=head2 C<puts> + +Send data to the client - $ret = $r->print(@msg); + $cnt = $r->puts(@msg); =over 4 -=item obj: C<$r> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) +=item obj: C<$r> +( C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>> ) + +=item arg1: C<@msg> ( ARRAY ) + +Data to send -=item arg1: C<@msg> (ARRAY) +=item ret: C<$cnt> ( number ) -=item ret: C<$ret> (number) +How many bytes were sent (or buffered) + +=item excpt: C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror>> + +=item since: 1.99_10 =back +C<puts()> is similar to C<L<print()|/C_print_>>, but it won't attempt +to flush data, no matter what the value of STDOUT stream's C<$|> +is. Therefore assuming that STDOUT stream's C<$|> is true, this method +should be a tiny bit faster than C<L<print()|/C_print_>>, especially +if small strings are printed. + + @@ -144,26 +186,43 @@ Read data from the client. - $read_count = $r->read($buffer, $len, $offset); - -META: same as COR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4read, minus the filehandle argument + $cnt = $r->read($buffer, $len); + $cnt = $r->read($buffer, $len, $offset); =over 4 -=item obj: C<$r> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) +=item obj: C<$r> +( C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>> ) + +=item arg1: C<$buffer> ( SCALAR ) + +The buffer to populate with the read data + +=item arg2: C<$len> ( number ) -=item arg1: C<$buffer> (scalar) +How many bytes to attempt to read -=item arg2: C<$len> (scalar) +=item opt arg3: C<$offset> ( number ) -=item arg3: C<$offset> (number) +If a non-zero C<$offset> is specified, the read data will be placed at +that offset in the C<$buffer>. -=item ret: C<$read_count> (number) +META: negative offset and \0 padding are not supported at the moment + +=item ret: C<$cnt> ( number ) How many characters were actually read +=item excpt: C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror>> + +=item since: 1.99_10 + =back +This method shares a lot of similarities with the Perl core C<read()> +function. The main difference in the error handling, which is done via +C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror exceptions|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror>> + @@ -171,39 +230,74 @@ Flush any buffered data to the client. - $ret = $r->rflush(); + $r->rflush(); =over 4 -=item obj: C<$r> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) +=item obj: C<$r> +( C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>> ) + +=item ret: no return value -=item ret: C<$ret> (integer) +=item since: 1.99_15 =back -Unless C<$|> E<gt> 0, data sent via C<L<$r-E<gt>print()|/C_print_>> is -buffered. This method flushes that data to the client. +Unless STDOUT stream's C<$|> is false, data sent via +C<L<$r-E<gt>print()|/C_print_>> is buffered. This method flushes that +data to the client. + =head2 C<sendfile> -META: Autogenerated - needs to be reviewed/completed +Send a file or a part of it - $ret = $r->sendfile($filename, $offset, $len); + $rc = $r->sendfile($filename); + $rc = $r->sendfile($filename, $offset); + $rc = $r->sendfile($filename, $offset, $len); =over 4 -=item obj: C<$r> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) +=item obj: C<$r> +( C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>> ) + +=item arg1: C<$filename> ( string ) + +The full path to the file (using C</> on all systems) + +=item opt arg2: C<$offset> ( integer ) + +Offset into the file to start sending. + +No offset is used if C<$offset> is not specified. -=item arg1: C<$filename> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) +=item opt arg3: C<$len> ( integer ) -=item arg2: C<$offset> (integer) +How many bytes to send. -=item arg3: C<$len> (integer) +If not specified the whole file is sent (or a part of it, if +C<$offset> if specified) -=item ret: C<$ret> (integer) +=item ret: C<$rc> ( C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst status +constant|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst>> ) + +On success, +C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4SUCCESS|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst/C_APR__SUCCESS_>> is +returned. + +In case of a failure -- a failure code is returned, in which case +normally it should be returned to the caller. + +=item excpt: C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror>> + +Exceptions are thrown only when this function is called in the VOID +context. So if you don't want to handle the errors, just don't ask for +a return value and the function will handle all the errors on its own. + +=item since: 1.99_15 =back @@ -213,218 +307,277 @@ =head2 C<write> -META: Autogenerated - needs to be reviewed/completed - -Write data to the client +Send partial string to the client - $ret = $r->write($buffer, $bufsiz, $offset); + $cnt = $r->write($buffer); + $cnt = $r->write($buffer, $len); + $cnt = $r->write($buffer, $len, $offset); =over 4 -=item obj: C<$r> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) +=item obj: C<$r> +( C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>> ) + +=item arg1: C<$buffer> ( SCALAR ) -=item arg1: C<$buffer> (scalar) +The string with data -=item arg2: C<$bufsiz> (scalar) +=item opt arg2: C<$len> ( SCALAR ) -=item arg3: C<$offset> (number) +How many bytes to send. If not specified, or -1 is specified, all the +data in C<$buffer> (or starting from C<$offset>) will be sent. -=item ret: C<$ret> (number) +=item opt arg3: C<$offset> ( number ) + +Offset into the C<$buffer> string. + +=item ret: C<$cnt> ( number ) + +How many bytes were sent (or buffered) + +=item excpt: C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror>> + +=item since: 1.99_10 =back +Examples: +Assuming that we have a string: + $string = "123456789"; -=head1 TIE Interface +Then: -=head2 C<OPEN> + $r->write($string); -META: Autogenerated - needs to be reviewed/completed +sends: - $ret = OPEN($self, $arg1, $arg2); + 123456789 -=over 4 +Whereas: -=item obj: C<$self> (scalar) + $r->write($string, 3); -=item arg1: C<$arg1> (scalar) +sends: -=item arg2: C<$arg2> (scalar) + 123 -=item ret: C<$ret> (integer) +And: -=back + $r->write($string, 3, 5); +sends: -=head2 C<UNTIE> + 678 -META: Autogenerated - needs to be reviewed/completed +Finally: + $r->write($string, -1, 5); +sends: - $ret = $r->UNTIE($refcnt); + 6789 -=over 4 -=item obj: C<$r> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) -=item arg1: C<$refcnt> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) -=item ret: C<$ret> (scalar) -=back +=head1 TIE Interface +The TIE interface implementation. This interface is used for HTTP +request handlers, when running under C<L<SetHandler +perl-script|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4user888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onfig888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onfig/C_perl_script_>> and +Perl doesn't have perlio enabled. -=head2 C<PRINTF> +See the I<perltie> manpage for more information. -META: Autogenerated - needs to be reviewed/completed - $ret = PRINTF(...); +=head2 C<BINMODE> =over 4 -=item obj: C<...> (scalar) - -=item ret: C<$ret> (number) +=item since: 1.99_10 =back +NoOP +See the I<binmode> Perl entry in the I<perlfunc> manpage =head2 C<CLOSE> -META: Autogenerated - needs to be reviewed/completed +=over 4 - $ret = $r->CLOSE(); +=item since: 1.99_10 -=over 4 +=back -=item obj: C<$r> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) +NoOP -=item ret: C<$ret> (scalar) +See the I<close> Perl entry in the I<perlfunc> manpage -=back +=head2 C<FILENO> +=over 4 +=item since: 1.99_10 -=head2 C<PRINT> +=back -META: Autogenerated - needs to be reviewed/completed +See the I<fileno> Perl entry in the I<perlfunc> manpage - $ret = PRINT(...); -=over 4 +=head2 C<GETC> -=item obj: C<...> (scalar) +=over 4 -=item ret: C<$ret> (number) +=item since: 1.99_10 =back +See the I<getc> Perl entry in the I<perlfunc> manpage -=head2 C<BINMODE> +=head2 C<OPEN> -META: Autogenerated - needs to be reviewed/completed +=over 4 +=item since: 1.99_10 +=back - $ret = $r->BINMODE(); +See the I<open> Perl entry in the I<perlfunc> manpage -=over 4 -=item obj: C<$r> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) -=item ret: C<$ret> (scalar) -=back +=head2 C<PRINT> + +=over 4 +=item since: 1.99_10 +=back +See the I<print> Perl entry in the I<perlfunc> manpage -=head2 C<WRITE> -META: Autogenerated - needs to be reviewed/completed - $ret = $r->WRITE($buffer, $bufsiz, $offset); +=head2 C<PRINTF> =over 4 -=item obj: C<$r> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) +=item since: 1.99_10 -=item arg1: C<$buffer> (scalar) +=back -=item arg2: C<$bufsiz> (scalar) +See the I<printf> Perl entry in the I<perlfunc> manpage -=item arg3: C<$offset> (integer) -=item ret: C<$ret> (integer) + + +=head2 C<READ> + +=over 4 + +=item since: 1.99_10 =back +See the I<read> Perl entry in the I<perlfunc> manpage + =head2 C<TIEHANDLE> -META: Autogenerated - needs to be reviewed/completed +=over 4 + +=item since: 1.99_10 + +=back +See the I<tie> Perl entry in the I<perlfunc> manpage - $ret = TIEHANDLE($stashsv, $sv); + + +=head2 C<UNTIE> =over 4 -=item obj: C<$stashsv> (scalar) +=item since: 1.99_10 -=item arg1: C<$sv> (scalar) +=back -=item ret: C<$ret> (scalar) +NoOP + +See the I<untie> Perl entry in the I<perlfunc> manpage + + + + + +=head2 C<WRITE> + +=over 4 + +=item since: 1.99_10 =back +See the I<write> Perl entry in the I<perlfunc> manpage -=head2 C<READ> +=head1 Deprecated API -META: Autogenerated - needs to be reviewed/completed +The following methods are deprecated, Apache plans to remove those in +the future, therefore avoid using them. - $ret = $r->READ($buffer, $len, $offset); +=head2 C<get_client_block> -=over 4 +This method is deprecated since the C implementation is buggy and we +don't want you to use paulpearson@example.org. Instead use the plain +C<L<$r-E<gt>read()|/C_read_>>. -=item obj: C<$r> (C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec>>) -=item arg1: C<$buffer> (scalar) -=item arg2: C<$len> (scalar) -=item arg3: C<$offset> (integer) +=head2 C<setup_client_block> + +This method is deprecated since +C<L<$r-E<gt>get_client_block|/C__get_client_block_>> is deprecated. + + + + +=head2 C<should_client_block> + +This method is deprecated since +C<L<$r-E<gt>get_client_block|/C__get_client_block_>> is deprecated. -=item ret: C<$ret> (scalar) -=back 1.51 +11 -14 modperl-docs/src/docs/2.0/user/porting/compat.pod Index: compat.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/porting/compat.pod,v retrieving revision 1.50 retrieving revision 1.51 diff -u -u -r1.50 -r1.51 --- compat.pod 22 May 2004 21:55:52 -0000 1.50 +++ compat.pod 2 Jul 2004 23:17:53 -0000 1.51 @@ -858,8 +858,7 @@ =item * if one wishes to simply read POST data, there is the more modern -C<{setup,should,get}_client_block> API, and even more modern filter -API, along with continued support for C<read(STDIN, ...)> and +filter API, along with continued support for C<read(STDIN, ...)> and C<$r-E<gt>read($buf, $r-E<gt>headers_in-E<gt>{'content-length'}>) =back @@ -1019,8 +1018,9 @@ =head2 C<$r-E<gt>send_fd> -Apache 2.0 provides a new method C<sendfile()> instead of C<send_fd>, -so if your code used to do: +mod_perl 2.0 provides a new method +C<L<sendfile()|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestIO/C_sendfile_>> instead +of C<send_fd>, so if your code used to do: open my $fh, "<$file" or die "$!"; $r->send_fd($fh); @@ -1028,19 +1028,16 @@ now all you need is: - $r->sendfile($fh); + $r->sendfile($file); -There is also a compatibility implementation in pure perl in -C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4compat|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4compat>>. +There is also a compatibility implementation of send_fd in pure perl +in C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4compat|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4compat>>. +XXX: later we may provide a direct access to the real send_fd. That +will be possible if we figure out how to portably convert PerlIO/FILE +into apr_file_t (with help of apr_os_file_put, which expects a native +filehandle, so I'm not sure whether this will work on win32). -=head2 C<$r-E<gt>send_fd_length> - -currently available only in the 1.0 compatibility layer. The problem -is that Apache has changed the API and its functionality. See the -implementation in C<L<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4compat|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4compat>>. - -XXX: needs a better resolution =head2 C<$r-E<gt>send_http_header> --------------------------------------------------------------------- To unsubscribe, e-mail: paulpearson@example.org For additional commands, e-mail: paulpearson@example.org From docspaulpearson@example.org Fri Jul 02 23:18:36 2004 Return-Path: <docspaulpearson@example.org> Delivered-To: paulpearson@example.org Received: (qmail 25870 invoked from network); 2 Jul 2004 23:18:36 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (83.161.120.155) by minotaur-2.apache.org with SMTP; 2 Jul 2004 23:18:36 -0000 Received: (qmail 23533 invoked by uid 500); 2 Jul 2004 23:18:50 -0000 Delivered-To: paulpearson@example.org Received: (qmail 23286 invoked by uid 500); 2 Jul 2004 23:18:48 -0000 Mailing-List: contact paulpearson@example.org; run by ezmlm Precedence: bulk Reply-To: paulpearson@example.org List-Post: <mailto:paulpearson@example.org> List-Help: <mailto:paulpearson@example.org> List-Unsubscribe: <mailto:paulpearson@example.org> List-Subscribe: <mailto:paulpearson@example.org> Delivered-To: mailing list paulpearson@example.org Received: (qmail 23248 invoked by uid 500); 2 Jul 2004 23:18:48 -0000 Delivered-To: paulpearson@example.org X-ASF-Spam-Status: No, hits=0.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Date: 2 Jul 2004 23:18:30 -0000 Message-ID: <paulpearson@example.org> From: paulpearson@example.org To: paulpearson@example.org Subject: cvs commit: modperl-docs/src/docs/2.0/user/handlers protocols.pod X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N stas 2004/07/02 16:18:30 Modified: src/docs/2.0/user/handlers protocols.pod Log: use the correct way to break the while(1) loop in protocols reading from the client Revision Changes Path 1.25 +10 -22 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.24 retrieving revision 1.25 diff -u -u -r1.24 -r1.25 --- protocols.pod 10 Jun 2004 15:02:21 -0000 1.24 +++ protocols.pod 2 Jul 2004 23:18:30 -0000 1.25 @@ -352,13 +352,8 @@ while (1) { my $rc = $c->input_filters->get_brigade($bb_in, Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4MODE_GETLINE); - if ($rc != APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4SUCCESS && $rc != APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OF) { - my $error = APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4strerror($rc); - warn __PACKAGE__ . ": get_brigade: $error\n"; - last; - } - - last if $bb_in->is_empty; + last if $rc == APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OF; + die APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4strerror($rc) unless $rc == APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4SUCCESS; while (!$bb_in->is_empty) { my $b = $bb_in->first; @@ -447,9 +442,10 @@ If you look at the complete handler, the loop is terminated when one of the following conditions occurs: an error happens, the end of -stream bucket has been seen (no more input at the connection) or when -the received data contains nothing but new line characters which we -used to to tell the server to terminate the connection. +stream status code (C<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OF>) has been received (no more input at +the connection) or when the received data contains nothing but new +line characters which we used to to tell the server to terminate the +connection. Notice that this handler could be much simpler, since we don't modify the data. We could simply pass the whole brigade unmodified without @@ -479,13 +475,8 @@ while (1) { my $rc = $c->input_filters->get_brigade($bb, Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4MODE_GETLINE); - if ($rc != APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4SUCCESS && $rc != APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OF) { - my $error = APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4strerror($rc); - warn __PACKAGE__ . ": get_brigade: $error\n"; - last; - } - - last if $bb->is_empty; + last if $rc == APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OF; + die APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4strerror($rc) unless $rc == APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4SUCCESS; $c->output_filters->fflush($bb); } @@ -527,11 +518,8 @@ while (1) { my $rc = $c->input_filters->get_brigade($bb, Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4MODE_GETLINE); - if ($rc != APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4SUCCESS && $rc != APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OF) { - my $error = APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4strerror($rc); - warn __PACKAGE__ . ": get_brigade: $error\n"; - last; - } + last if $rc == APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OF; + die APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4rror888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4strerror($rc) unless $rc == APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4SUCCESS; next unless $bb->flatten(my $data); $bb->cleanup; --------------------------------------------------------------------- To unsubscribe, e-mail: paulpearson@example.org For additional commands, e-mail: paulpearson@example.org From docspaulpearson@example.org Sat Jul 03 17:44:42 2004 Return-Path: <docspaulpearson@example.org> Delivered-To: paulpearson@example.org Received: (qmail 86485 invoked from network); 3 Jul 2004 17:44:41 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (83.161.120.155) by minotaur-2.apache.org with SMTP; 3 Jul 2004 17:44:41 -0000 Received: (qmail 23200 invoked by uid 500); 3 Jul 2004 17:44:44 -0000 Delivered-To: paulpearson@example.org Received: (qmail 23074 invoked by uid 500); 3 Jul 2004 17:44:39 -0000 Mailing-List: contact paulpearson@example.org; run by ezmlm Precedence: bulk Reply-To: paulpearson@example.org List-Post: <mailto:paulpearson@example.org> List-Help: <mailto:paulpearson@example.org> List-Unsubscribe: <mailto:paulpearson@example.org> List-Subscribe: <mailto:paulpearson@example.org> Delivered-To: mailing list paulpearson@example.org Received: (qmail 22915 invoked by uid 500); 3 Jul 2004 17:44:34 -0000 Delivered-To: paulpearson@example.org X-ASF-Spam-Status: No, hits=0.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Date: 3 Jul 2004 17:44:27 -0000 Message-ID: <paulpearson@example.org> From: paulpearson@example.org To: paulpearson@example.org Subject: cvs commit: modperl-docs/src/docs/2.0/user/install install.pod X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N stas 2004/07/03 10:44:27 Modified: src/docs/2.0/user/install install.pod Log: typo Submitted by: paulpearson@example.org Revision Changes Path 1.55 +2 -3 modperl-docs/src/docs/2.0/user/install/install.pod Index: install.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/install/install.pod,v retrieving revision 1.54 retrieving revision 1.55 diff -u -u -r1.54 -r1.55 --- install.pod 20 Apr 2004 01:59:57 -0000 1.54 +++ install.pod 3 Jul 2004 17:44:27 -0000 1.55 @@ -505,9 +505,8 @@ =head4 MP_AP_PREFIX Apache installation prefix, under which the I<include/> directory with -Apache C header files can be found. For example if you've have -installed Apache 2.0 in directory I<\Apache2> on Win32, you should -use: +Apache C header files can be found. For example if you've installed +Apache 2.0 in directory I<\Apache2> on Win32, you should use: MP_AP_PREFIX=\Apache2 --------------------------------------------------------------------- To unsubscribe, e-mail: paulpearson@example.org For additional commands, e-mail: paulpearson@example.org From docspaulpearson@example.org Sun Jul 04 00:55:15 2004 Return-Path: <docspaulpearson@example.org> Delivered-To: paulpearson@example.org Received: (qmail 71822 invoked from network); 4 Jul 2004 00:55:15 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (83.161.120.155) by minotaur-2.apache.org with SMTP; 4 Jul 2004 00:55:15 -0000 Received: (qmail 24887 invoked by uid 500); 4 Jul 2004 00:55:19 -0000 Delivered-To: paulpearson@example.org Received: (qmail 24740 invoked by uid 500); 4 Jul 2004 00:55:15 -0000 Mailing-List: contact paulpearson@example.org; run by ezmlm Precedence: bulk Reply-To: paulpearson@example.org List-Post: <mailto:paulpearson@example.org> List-Help: <mailto:paulpearson@example.org> List-Unsubscribe: <mailto:paulpearson@example.org> List-Subscribe: <mailto:paulpearson@example.org> Delivered-To: mailing list paulpearson@example.org Received: (qmail 24638 invoked by uid 500); 4 Jul 2004 00:55:11 -0000 Delivered-To: paulpearson@example.org X-ASF-Spam-Status: No, hits=0.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Date: 4 Jul 2004 00:55:01 -0000 Message-ID: <paulpearson@example.org> From: paulpearson@example.org To: paulpearson@example.org Subject: cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N stas 2004/07/03 17:55:01 Modified: src/docs/2.0/user/handlers http.pod Log: remove dup Submitted by: David Arnold <paulpearson@example.org> Revision Changes Path 1.37 +0 -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.36 retrieving revision 1.37 diff -u -u -r1.36 -r1.37 --- http.pod 10 Jun 2004 15:02:21 -0000 1.36 +++ http.pod 4 Jul 2004 00:55:01 -0000 1.37 @@ -773,8 +773,6 @@ use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestUtil (); use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const -compile => qw(OK DECLINED HTTP_UNAUTHORIZED); - - use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Access(); use constant SECRET_LENGTH => 14; --------------------------------------------------------------------- To unsubscribe, e-mail: paulpearson@example.org For additional commands, e-mail: paulpearson@example.org From docspaulpearson@example.org Sun Jul 04 01:42:02 2004 Return-Path: <docspaulpearson@example.org> Delivered-To: paulpearson@example.org Received: (qmail 88853 invoked from network); 4 Jul 2004 01:42:02 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (83.161.120.155) by minotaur-2.apache.org with SMTP; 4 Jul 2004 01:42:02 -0000 Received: (qmail 15220 invoked by uid 500); 4 Jul 2004 01:42:03 -0000 Delivered-To: paulpearson@example.org Received: (qmail 15150 invoked by uid 500); 4 Jul 2004 01:42:01 -0000 Mailing-List: contact paulpearson@example.org; run by ezmlm Precedence: bulk Reply-To: paulpearson@example.org List-Post: <mailto:paulpearson@example.org> List-Help: <mailto:paulpearson@example.org> List-Unsubscribe: <mailto:paulpearson@example.org> List-Subscribe: <mailto:paulpearson@example.org> Delivered-To: mailing list paulpearson@example.org Received: (qmail 15076 invoked by uid 500); 4 Jul 2004 01:41:59 -0000 Delivered-To: paulpearson@example.org X-ASF-Spam-Status: No, hits=0.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Date: 4 Jul 2004 01:41:49 -0000 Message-ID: <paulpearson@example.org> From: paulpearson@example.org To: paulpearson@example.org Subject: cvs commit: modperl-docs/src/docs/2.0/api/ModPerl Const.pod X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N stas 2004/07/03 18:41:49 Modified: src/docs/2.0/api/Apache Const.pod src/docs/2.0/api/APR Const.pod src/docs/2.0/api/ModPerl Const.pod Log: add explanations about *888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst modules Revision Changes Path 1.13 +70 -0 modperl-docs/src/docs/2.0/api/Apache/Const.pod Index: Const.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Const.pod,v retrieving revision 1.12 retrieving revision 1.13 diff -u -u -r1.12 -r1.13 --- Const.pod 2 Jun 2004 19:09:52 -0000 1.12 +++ Const.pod 4 Jul 2004 01:41:49 -0000 1.13 @@ -2,9 +2,79 @@ Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const - Perl Interface for Apache Constants + + + + =head1 Synopsis + # make the constants available but don't import them use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const -compile => qw(constant names ...); + + # w/o the => syntax sugar + use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const ("-compile", qw(constant names ...)); + + # compile and import the constants + use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const qw(constant names ...); + + + + + +=head1 Description + +This package contains constants specific to C<Apache> features. + +mod_perl 2.0 comes with several hundreds of constants, which you don't +want to make available to your Perl code by default, due to CPU and +memory overhead. Therefore when you want to use a certain constant you +need to explicitly ask to make it available. + +For example, the code: + + use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const -compile => qw(FORBIDDEN OK); + +makes the constants C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4FORBIDDEN> and C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK> available +to your code, but they aren't imported. In which case you need to use +a fully qualified constants, as in: + + return Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK; + +If you drop the argument C<-compile> and write: + + use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const qw(FORBIDDEN OK); + +Then both constants are imported into your code's namespace and can be +used standalone like so: + + return OK; + +Both, due to the extra memory requirement, when importing symbols, and +since there are constants in other namespaces (e.g., +C<L<APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4PR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst>> and +C<L<ModPerl888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4ModPerl888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst>>, and non-mod_perl +modules) which may contain the same names, it's not recommended to +import constants. I.e. you want to use the C<-compile> construct. + +Finaly, in Perl C<=E<gt>> is almost the same as the comma operator. It +can be used as syntax sugar making it more clear when there is a +key-value relation between two arguments, and also it automatically +parses its lefthand argument (the key) as a string, so you don't need +to quote it. + +If you don't want to use that syntax, instead of writing: + + use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const -compile => qw(FORBIDDEN OK); + +you could write: + + use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const "-compile", qw(FORBIDDEN OK); + +and for parentheses-lovers: + + use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const ("-compile", qw(FORBIDDEN OK)); + + =head1 Constants 1.21 +31 -0 modperl-docs/src/docs/2.0/api/APR/Const.pod Index: Const.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/APR/Const.pod,v retrieving revision 1.20 retrieving revision 1.21 diff -u -u -r1.20 -r1.21 --- Const.pod 2 Jun 2004 19:09:52 -0000 1.20 +++ Const.pod 4 Jul 2004 01:41:49 -0000 1.21 @@ -2,9 +2,40 @@ APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst - Perl Interface for APR Constants + + + + + =head1 Synopsis + # make the constants available but don't import them use APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst -compile => qw(constant names ...); + + # w/o the => syntax sugar + use APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst ("-compile", qw(constant names ...)); + + # compile and import the constants + use APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst qw(constant names ...); + + + + + + + +=head1 Description + +This package contains constants specific to C<APR> features. + +Refer to C<L<the Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const description +section|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const/Description>> for more +information. + + + + + =head1 Constants 1.3 +29 -0 modperl-docs/src/docs/2.0/api/ModPerl/Const.pod Index: Const.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/ModPerl/Const.pod,v retrieving revision 1.2 retrieving revision 1.3 diff -u -u -r1.2 -r1.3 --- Const.pod 22 May 2004 02:03:28 -0000 1.2 +++ Const.pod 4 Jul 2004 01:41:49 -0000 1.3 @@ -2,9 +2,38 @@ ModPerl888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst -- ModPerl Constants + + + + =head1 Synopsis + # make the constants available but don't import them use ModPerl888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst -compile => qw(constant names ...); + + # w/o the => syntax sugar + use ModPerl888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst ("-compile", qw(constant names ...)); + + # compile and import the constants + use ModPerl888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4onst qw(constant names ...); + + + + + + +=head1 Description + +This package contains constants specific to mod_perl features. + +Refer to C<L<the Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const description +section|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4api888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4pach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const/Description>> for more +information. + + + + + =head1 Constants --------------------------------------------------------------------- To unsubscribe, e-mail: paulpearson@example.org For additional commands, e-mail: paulpearson@example.org From docspaulpearson@example.org Sun Jul 04 02:38:31 2004 Return-Path: <docspaulpearson@example.org> Delivered-To: paulpearson@example.org Received: (qmail 2648 invoked from network); 4 Jul 2004 02:38:31 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (83.161.120.155) by minotaur-2.apache.org with SMTP; 4 Jul 2004 02:38:31 -0000 Received: (qmail 34011 invoked by uid 500); 4 Jul 2004 02:38:35 -0000 Delivered-To: paulpearson@example.org Received: (qmail 33846 invoked by uid 500); 4 Jul 2004 02:38:31 -0000 Mailing-List: contact paulpearson@example.org; run by ezmlm Precedence: bulk Reply-To: paulpearson@example.org List-Post: <mailto:paulpearson@example.org> List-Help: <mailto:paulpearson@example.org> List-Unsubscribe: <mailto:paulpearson@example.org> List-Subscribe: <mailto:paulpearson@example.org> Delivered-To: mailing list paulpearson@example.org Received: (qmail 33775 invoked by uid 500); 4 Jul 2004 02:38:28 -0000 Delivered-To: paulpearson@example.org X-ASF-Spam-Status: No, hits=0.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Date: 4 Jul 2004 02:38:15 -0000 Message-ID: <paulpearson@example.org> From: paulpearson@example.org To: paulpearson@example.org Subject: cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N stas 2004/07/03 19:38:15 Modified: src/docs/2.0/user/handlers http.pod Log: another dup Submitted by: David Arnold <paulpearson@example.org> Revision Changes Path 1.38 +0 -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.37 retrieving revision 1.38 diff -u -u -r1.37 -r1.38 --- http.pod 4 Jul 2004 00:55:01 -0000 1.37 +++ http.pod 4 Jul 2004 02:38:15 -0000 1.38 @@ -912,8 +912,6 @@ use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestUtil (); use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const -compile => qw(OK HTTP_UNAUTHORIZED); - - use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Access (); my %protected = ( 'admin' => ['stas'], --------------------------------------------------------------------- To unsubscribe, e-mail: paulpearson@example.org For additional commands, e-mail: paulpearson@example.org From docspaulpearson@example.org Sun Jul 04 07:38:05 2004 Return-Path: <docspaulpearson@example.org> Delivered-To: paulpearson@example.org Received: (qmail 86276 invoked from network); 4 Jul 2004 07:38:05 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (83.161.120.155) by minotaur-2.apache.org with SMTP; 4 Jul 2004 07:38:05 -0000 Received: (qmail 90671 invoked by uid 500); 4 Jul 2004 07:38:11 -0000 Delivered-To: paulpearson@example.org Received: (qmail 90633 invoked by uid 500); 4 Jul 2004 07:38:10 -0000 Mailing-List: contact paulpearson@example.org; run by ezmlm Precedence: bulk Reply-To: paulpearson@example.org List-Post: <mailto:paulpearson@example.org> List-Help: <mailto:paulpearson@example.org> List-Unsubscribe: <mailto:paulpearson@example.org> List-Subscribe: <mailto:paulpearson@example.org> Delivered-To: mailing list paulpearson@example.org Delivered-To: moderator for paulpearson@example.org Received: (qmail 16779 invoked by uid 500); 4 Jul 2004 04:16:42 -0000 Delivered-To: paulpearson@example.org X-ASF-Spam-Status: No, hits=0.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Date: 4 Jul 2004 04:16:31 -0000 Message-ID: <paulpearson@example.org> From: paulpearson@example.org To: paulpearson@example.org Subject: cvs commit: modperl-docs/src/docs/1.0/guide databases.pod X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N perrin 2004/07/03 21:16:30 Modified: src/docs/1.0/guide databases.pod Log: Added note about issues with InnoDB tables and default isolation level Revision Changes Path 1.10 +22 -0 modperl-docs/src/docs/1.0/guide/databases.pod Index: databases.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/databases.pod,v retrieving revision 1.9 retrieving revision 1.10 diff -u -r1.9 -r1.10 --- databases.pod 9 May 2002 10:34:43 -0000 1.9 +++ databases.pod 4 Jul 2004 04:16:30 -0000 1.10 @@ -438,6 +438,28 @@ This can tie up the server and prevent other threads from updating the tables. +=head1 Transactions Not Committed with MySQL InnoDB Tables + +Sometimes, when using MySQL's InnoDB table type, you may notice that +changes you committed in one process don't seem to be visible to other +processes. You may not be aware that InnoDB tables use a default +approach to transactions that is actually more cautious than PostgreSQL +or Oracle's default. It's called "repeatable read", and the gist of +it is that you don't see updates made in other processes since your +last commit. There is an explanation of this here: +http://dev.mysql.com/doc/mysql/en/InnoDB_Consistent_read_example.html + +This is actually not directly related to mod_perl, but you wouldn't +notice this issue when using CGI because reconecting to the database on +each request resets things just as doing a commit does. It is the +persistent connections used with mod_perl that make this issue visible. + +If you suspect this is causing you problems, the simplest way to +deal with it is to change the isolation level to "read committed" -- +which is more like what PostgreSQL and Oracle do by default -- with +the "set transaction" command, described here: +http://dev.mysql.com/doc/mysql/en/InnoDB_transaction_isolation.html + =head1 Optimize: Run Two SQL Engine Servers Sometimes you end up running many databases on the same machine. These --------------------------------------------------------------------- To unsubscribe, e-mail: paulpearson@example.org For additional commands, e-mail: paulpearson@example.org From docspaulpearson@example.org Sun Jul 04 07:38:31 2004 Return-Path: <docspaulpearson@example.org> Delivered-To: paulpearson@example.org Received: (qmail 86400 invoked from network); 4 Jul 2004 07:38:31 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (83.161.120.155) by minotaur-2.apache.org with SMTP; 4 Jul 2004 07:38:31 -0000 Received: (qmail 91525 invoked by uid 500); 4 Jul 2004 07:38:38 -0000 Delivered-To: paulpearson@example.org Received: (qmail 91414 invoked by uid 500); 4 Jul 2004 07:38:35 -0000 Mailing-List: contact paulpearson@example.org; run by ezmlm Precedence: bulk Reply-To: paulpearson@example.org List-Post: <mailto:paulpearson@example.org> List-Help: <mailto:paulpearson@example.org> List-Unsubscribe: <mailto:paulpearson@example.org> List-Subscribe: <mailto:paulpearson@example.org> Delivered-To: mailing list paulpearson@example.org Delivered-To: moderator for paulpearson@example.org Received: (qmail 71841 invoked by uid 500); 4 Jul 2004 03:51:54 -0000 Delivered-To: paulpearson@example.org X-ASF-Spam-Status: No, hits=0.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Date: 4 Jul 2004 03:51:41 -0000 Message-ID: <paulpearson@example.org> From: paulpearson@example.org To: paulpearson@example.org Subject: cvs commit: modperl-docs/src/download third_party.pod X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N perrin 2004/07/03 20:51:41 Modified: src/docs/1.0/guide performance.pod src/download third_party.pod Log: Added notes on Flood and Webstone benchmarking tools Revision Changes Path 1.29 +23 -0 modperl-docs/src/docs/1.0/guide/performance.pod Index: performance.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/performance.pod,v retrieving revision 1.28 retrieving revision 1.29 diff -u -r1.28 -r1.29 --- performance.pod 10 May 2004 06:44:59 -0000 1.28 +++ performance.pod 4 Jul 2004 03:51:40 -0000 1.29 @@ -477,6 +477,29 @@ It's available from CPAN. +=item * C<Webstone> + +This tool is somewhat complex to set up, but once you get it running +it gives you stats that you could only duplicate with ab or http_load +if you did quite a bit of extra scripting around them. It also allows +multiple client machines to be used for providing heavy loads. This tool +is useful if you need to know things like at what point people start +finding your sight slow, as opposed to at what point the server becomes +unresponsive. + +L<Webstone download|downlo888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4third_party/Webstone____another_webserver_Benchmarking_tool> + +=item * C<Flood> + +Flood is a load-tester being developed through the Apache Software +Foundation. From the Flood FAQ: + +"Flood is a profile-driven HTTP load tester. In layman's terms, it means +that flood is capable of generating large amounts of web traffic. +Flood's flexibility and power arises in its configuration syntax. +It is able to work well with dynamic content." + +L<Flood download|downlo888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4third_party/Flood____another_webserver_Benchmarking_tool> =back 1.9 +8 -0 modperl-docs/src/download/third_party.pod Index: third_party.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/download/third_party.pod,v retrieving revision 1.8 retrieving revision 1.9 diff -u -r1.8 -r1.9 --- third_party.pod 27 Oct 2003 05:23:44 -0000 1.8 +++ third_party.pod 4 Jul 2004 03:51:41 -0000 1.9 @@ -68,6 +68,14 @@ http://www.acme.com/software/http_load/ +=head1 Webstone -- another webserver Benchmarking tool + +http://www.mindcraft.com/webstone/ + +=head1 Flood -- another webserver Benchmarking tool + +http://httpd.apache.org/test/flood/ + =head1 ab -- ApacheBench ApacheBench comes with the Apache distribution. --------------------------------------------------------------------- To unsubscribe, e-mail: paulpearson@example.org For additional commands, e-mail: paulpearson@example.org From docspaulpearson@example.org Sun Jul 04 08:35:33 2004 Return-Path: <docspaulpearson@example.org> Delivered-To: paulpearson@example.org Received: (qmail 3012 invoked from network); 4 Jul 2004 08:35:33 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (83.161.120.155) by minotaur-2.apache.org with SMTP; 4 Jul 2004 08:35:33 -0000 Received: (qmail 2358 invoked by uid 500); 4 Jul 2004 08:35:41 -0000 Delivered-To: paulpearson@example.org Received: (qmail 2250 invoked by uid 500); 4 Jul 2004 08:35:38 -0000 Mailing-List: contact paulpearson@example.org; run by ezmlm Precedence: bulk Reply-To: paulpearson@example.org List-Post: <mailto:paulpearson@example.org> List-Help: <mailto:paulpearson@example.org> List-Unsubscribe: <mailto:paulpearson@example.org> List-Subscribe: <mailto:paulpearson@example.org> Delivered-To: mailing list paulpearson@example.org Received: (qmail 2147 invoked by uid 500); 4 Jul 2004 08:35:35 -0000 Delivered-To: paulpearson@example.org X-ASF-Spam-Status: No, hits=0.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Date: 4 Jul 2004 08:35:23 -0000 Message-ID: <paulpearson@example.org> From: paulpearson@example.org To: paulpearson@example.org Subject: cvs commit: modperl-docs/src/docs/2.0/user/handlers protocols.pod X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N stas 2004/07/04 01:35:23 Modified: src/docs/2.0/user/handlers protocols.pod Log: backport the original Command Server protocol example written by doug Revision Changes Path 1.26 +274 -0 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.25 retrieving revision 1.26 diff -u -u -r1.25 -r1.26 --- protocols.pod 2 Jul 2004 23:18:30 -0000 1.25 +++ protocols.pod 4 Jul 2004 08:35:23 -0000 1.26 @@ -546,6 +546,280 @@ +=head1 Examples + +Following are some practical examples. + +META: If you have written an interesting, but not too complicated +module, which others can learn from, please submit a pod to the +L<mailing list|maillist888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4modperl> so we can include it here. + + + + + +=head2 Command Server + +The C<MyApach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4CommandServer> example is based on the example in the +"TCP Servers with IO888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Socket" section of the I<perlipc> manpage. Of +course, we don't need C<IO888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Socket> since Apache takes care of those +details for us. The rest of that example can still be used to +illustrate implementing a simple text protocol. In this case, one +where a command is sent by the client to be executed on the server +side, with results sent back to the client. + +The C<MyApach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4CommandServer> handler will support four commands: +C<motd>, C<date>, C<who> and C<quit>. These are probably not commands +which can be exploited, but should we add such commands, we'll want to +limit access based on ip address/hostname, authentication and +authorization. Protocol handlers need to take care of these tasks +themselves, since we bypass the HTTP protocol handler. + +Here is the whole module: + + package MyApach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4CommandServer; + + use strict; + use warnings FATAL => 'all'; + + use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Connection (); + use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestUtil (); + use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4HookRun (); + use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Access (); + use APR888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Socket (); + + use Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Const -compile => qw(OK DONE DECLINED); + + my @cmds = qw(motd date who quit); + my %commands = map { $_, \&{$_} } @cmds; + + sub handler { + my $c = shift; + my $socket = $c->client_socket; + + if ((my $rc = login($c)) != Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK) { + $socket->send("Access Denied\n"); + return $rc; + } + + $socket->send("Welcome to " . __PACKAGE__ . + "\nAvailable commands: @cmds\n"); + + while (1) { + my $cmd; + next unless $cmd = getline($socket); + + if (my $sub = $commands{$cmd}) { + last unless $sub->($socket) == Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK; + } + else { + $socket->send("Commands: @cmds\n"); + } + } + + return Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK; + } + + sub login { + my $c = shift; + + my $r = Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec->new($c); + $r->location_merge(__PACKAGE__); + + for my $method (qw(run_access_checker run_check_user_id + run_auth_checker)) { + my $rc = $r->$method(); + + if ($rc != Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK and $rc != Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4DECLINED) { + return $rc; + } + + last unless $r->some_auth_required; + + unless ($r->user) { + my $socket = $c->client_socket; + my $username = prompt($socket, "Login"); + my $password = prompt($socket, "Password"); + + $r->set_basic_credentials($username, $password); + } + } + + return Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK; + } + + sub getline { + my $socket = shift; + + my $line; + $socket->recv($line, 1024); + return unless $line; + $line =~ s/[\r\n]*$//; + + return $line; + } + + sub prompt { + my($socket, $msg) = @_; + + $socket->send("$msg: "); + getline($socket); + } + + sub motd { + my $socket = shift; + + open my $fh, '/etc/motd' or return; + local $/; + $socket->send(scalar <$fh>); + close $fh; + + return Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK; + } + + sub date { + my $socket = shift; + + $socket->send(scalar(localtime) . "\n"); + + return Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK; + } + + sub who { + my $socket = shift; + + # make -T happy + local $ENV{PATH} = "/bin:/usr/bin"; + + $socket->send(scalar `who`); + + return Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK; + } + + sub quit { Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4DONE } + + 1; + __END__ + + +Next, let's explain what this module does in details. + +As with all C<PerlProcessConnectionHandlers>, we are passed an +C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Connection> object as the first argument. Again, we will be +directly accessing the client socket via the I<client_socket> method. +The I<login> subroutine is called to check if access by this client +should be allowed. This routine makes up for what we lost with the +core HTTP protocol handler bypassed. First we call the +C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec> I<new> method, which returns a I<request_rec> +object, just like that which is passed at request time to L<HTTP +protocol|docs888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4.888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4user888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4handlers888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4http> C<Perl*Handlers> and +returned by the subrequest API methods, I<lookup_uri> and +I<lookup_file>. However, this "fake request" does not run handlers +for any of the phases, it simply returns an object which we can use to +do that ourselves. The C<location_merge()> method is passed the +C<location> for this request, it will look up the +C<E<lt>LocationE<gt>> section that matches the given name and merge it +with the default server configuration. For example, should we only +wish to allow access to this server from certain locations: + + <Location MyApach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4CommandServer> + deny from all + allow from 10.* + </Location> + +The C<location_merge()> method only looks up and merges the +configuration, we still need to apply it. This is done in I<for> +loop, iterating over three methods: C<run_access_checker()>, +C<run_check_user_id()> and C<run_auth_checker()>. These methods will +call directly into the Apache functions that invoke module handlers +for these phases and will return an integer status code, such as +C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK>, C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4DECLINED> or C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4FORBIDDEN>. If +I<run_access_check> returns something other than C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK> or +C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4DECLINED>, that status will be propagated up to the handler +routine and then back up to Apache. Otherwise, the access check +passed and the loop will break unless C<some_auth_required()> returns +true. This would be false given the previous configuration example, +but would be true in the presence of a C<require> directive, such as: + + <Location MyApach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4CommandServer> + deny from all + allow from 10.* + require user dougm + </Location> + +Given this configuration, C<some_auth_required()> will return true. +The C<user()> method is then called, which will return false if we +have not yet authenticated. A C<prompt()> utility is called to read +the username and password, which are then injected into the +C<headers_in()> table using the C<set_basic_credentials()> method. +The I<Authenticate> field in this table is set to a I<base64> encoded +value of the username:password pair, exactly the same format a browser +would send for I<Basic authentication>. Next time through the loop +I<run_check_user_id> is called, which will in turn invoke any +authentication handlers, such as I<mod_auth>. When I<mod_auth> calls +the C<ap_get_basic_auth_pw()> API function (as all C<Basic> auth +modules do), it will get back the username and password we injected. +If we fail authentication a C<401> status code is returned which we +propagate up. Otherwise, authorization handlers are run via +C<run_auth_checker()>. Authorization handlers normally need the +I<user> field of the C<request_rec> for its checks and that field was +filled in when I<mod_auth> called C<ap_get_basic_auth_pw()>. + +Provided login is a success, a welcome message is printed and main +request loop entered. Inside the loop the C<getline()> function +returns just one line of data, with newline characters stripped. If +the string sent by the client is in our command table, the command is +then invoked, otherwise a usage message is sent. If the command does +not return C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4OK>, we break out of the loop. + +Let's use this configuration: + + Listen 8085 + <VirtualHost _default_:8085> + PerlProcessConnectionHandler MyApach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4CommandServer + + <Location MyApach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4CommandServer> + allow from 83.161.120.155 + require user dougm + satisfy any + AuthUserFile /tmp/basic-auth + </Location> + </VirtualHost> + +The auth file can be created with the help of C<htpasswd> utility +coming bundled with the Apache server. For example to create a file +F</tmp/basic-auth> and add a password entry for user I<dougm> with +password I<foobar> we do: + + % htpasswd -bc /tmp/basic-auth dougm foobar + +Now we are ready to try the command server: + + % telnet localhost 8085 + Trying 83.161.120.155... + Connected to localhost (83.161.120.155). + Escape character is '^]'. + Login: dougm + Password: foobar + Welcome to MyApach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4CommandServer + Available commands: motd date who quit + motd + Have a lot of fun... + date + Mon Mar 12 19:20:10 PST 2001 + who + dougm tty1 Mar 12 00:49 + dougm pts/0 Mar 12 11:23 + dougm pts/1 Mar 12 14:08 + dougm pts/2 Mar 12 17:09 + quit + Connection closed by foreign host. + + + + + + --------------------------------------------------------------------- To unsubscribe, e-mail: paulpearson@example.org For additional commands, e-mail: paulpearson@example.org From docspaulpearson@example.org Sun Jul 04 08:37:59 2004 Return-Path: <docspaulpearson@example.org> Delivered-To: paulpearson@example.org Received: (qmail 3655 invoked from network); 4 Jul 2004 08:37:59 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (83.161.120.155) by minotaur-2.apache.org with SMTP; 4 Jul 2004 08:37:59 -0000 Received: (qmail 6503 invoked by uid 500); 4 Jul 2004 08:38:05 -0000 Delivered-To: paulpearson@example.org Received: (qmail 6392 invoked by uid 500); 4 Jul 2004 08:38:02 -0000 Mailing-List: contact paulpearson@example.org; run by ezmlm Precedence: bulk Reply-To: paulpearson@example.org List-Post: <mailto:paulpearson@example.org> List-Help: <mailto:paulpearson@example.org> List-Unsubscribe: <mailto:paulpearson@example.org> List-Subscribe: <mailto:paulpearson@example.org> Delivered-To: mailing list paulpearson@example.org Received: (qmail 6329 invoked by uid 500); 4 Jul 2004 08:38:00 -0000 Delivered-To: paulpearson@example.org X-ASF-Spam-Status: No, hits=0.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Date: 4 Jul 2004 08:37:49 -0000 Message-ID: <paulpearson@example.org> From: paulpearson@example.org To: paulpearson@example.org Subject: cvs commit: modperl-docs/src/docs/2.0 TODO X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N stas 2004/07/04 01:37:49 Modified: src/docs/2.0 TODO Log: updates Revision Changes Path 1.9 +0 -242 modperl-docs/src/docs/2.0/TODO Index: TODO =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/2.0/TODO,v retrieving revision 1.8 retrieving revision 1.9 diff -u -u -r1.8 -r1.9 --- TODO 10 May 2004 05:17:58 -0000 1.8 +++ TODO 4 Jul 2004 08:37:49 -0000 1.9 @@ -7,16 +7,6 @@ mp2doc - replacement for perldoc for modules that get installed into Apache2/ ---- - -*** Areas that would be nice to document first *** - -- Automatic API docs generator from .h files - Owner: Lyle Brooks? - -- Directive handlers (custom config handlers) - Owner: stas - *** General items *** --- @@ -88,238 +78,6 @@ --- - -Need to integrate the following example, removed from overview.pod, in -protocols.pod: - - -=head2 Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4CommandServer - -Our first protocol handler example took advange of Apache's server -framework, but did not tap into any other modules. The next example -is based on the example in the "TCP Servers with IO888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Socket" section -of the I<perlipc> manpage. Of course, we don't need C<IO888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Socket> -since Apache takes care of those details for us. The rest of that -example can still be used to illustrate implementing a simple text -protocol. In this case, one where a command is sent by the client to -be executed on the server side, with results sent back to the client. - -The C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4CommandServer> handler will support four commands: -C<motd>, C<date>, C<who> and C<quit>. These are probably not commands -which can be exploited, but should we add such commands, we'll want to -limit access based on ip address/hostname, authentication and -authorization. Protocol handlers need to take care of these tasks -themselves, since we bypass the HTTP protocol handler. - -As with all C<PerlProcessConnectionHandlers>, we are passed an -C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4Connection> object as the first argument. Again, we will be -directly accessing the client socket via the I<client_socket> method. -The I<login> subroutine is called to check if access by this client -should be allowed. This routine makes up for what we lost with the -core HTTP protocol handler bypassed. First we call the -C<Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4RequestRec> I<new> method, which returns a I<request_rec> -object, just like that which is passed at request time to -C<Perl*Handlers> and returned by the subrequest API methods, -I<lookup_uri> and I<lookup_file>. However, this "fake request" does -not run handlers for any of the phases, it simply returns an object -which we can use to do that ourselves. The C<location_merge> method -is passed the "location" for this request, it will look up the -C<E<lt>LocationE<gt>> section that matches the given name and merge it -with the default server configuration. For example, should we only -wish to allow access to this server from certain locations: - - <Location Apach888a:dbb7:2d49:b3f6:8605:bf4e:caed:e5a4CommandServer> - deny from all - allow from 10.* - </Location> - -The I<location_merge> method only looks up and merges the -configuration, we still need to apply it. This is done in I<for> -loop, iterating over three methods: I<run_access_checker>, -I<run_check_user_id> and I<run_auth_checker>. These methods will call -directly into the Apache functions that invoke module handlers for -these phases and will return an integer status code, such as C<OK>, -C<DECLINED> or C<FORBIDDEN>. If I<run_access_check> returns something -other than C<OK> or C<DECLINED>, that status will be propagated up to -the handler routine and then back up to Apache. Otherwise, the access -check passed and the loop will break unless I<some_auth_required> -returns true. This would be false given the previous configuration -example, but would be true in the presense of a I<require> directive, -such
{'source': 'Apache Software Foundation Public Mail Archives'}