perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/user/coding coding.pod
Date Tue, 02 Mar 2004 21:05:32 GMT
stas        2004/03/02 13:05:32

  Modified:    src/docs/2.0/user/coding coding.pod
  Log:
  - new: Generating HTTP Response Headers
  - update: Forcing HTTP Response Headers Out
  - new: registry section
  - new: registry: A Look Behind the Scenes
  - new: registry: Getting the $r Object
  
  Revision  Changes    Path
  1.30      +187 -8    modperl-docs/src/docs/2.0/user/coding/coding.pod
  
  Index: coding.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/coding/coding.pod,v
  retrieving revision 1.29
  retrieving revision 1.30
  diff -u -u -r1.29 -r1.30
  --- coding.pod	12 Jan 2004 08:42:52 -0000	1.29
  +++ coding.pod	2 Mar 2004 21:05:32 -0000	1.30
  @@ -203,17 +203,106 @@
   In the following sections we discuss the specifics of Apache behavior
   relevant to mod_perl developers.
   
  -=head2 Sending HTTP Response Headers
  +=head2 HTTP Response Headers
  +
  +=head3 Generating HTTP Response Headers
  +
  +The best approach for generating HTTP response headers is by using the
  +L<mod_perl API|docs::2.0::api::Apache::RequestRec>. Some common
  +headers have dedicated methods, others are set by manipulating the
  +C<L<headers_out|docs::2.0::api::Apache::RequestRec/C_headers_out_>>
  +table directly.
  +
  +For example to set the I<Content-type> header you should call
  +C<L<$r-E<gt>content_type|docs::2.0::api::Apache::RequestRec/C_content_type_>>:
  +
  +  use Apache::RequestRec ();
  +  $r->content_type('text/html');
  +
  +To C<L<set|docs::2.0::api::APR::Table/C_set_>> a custom header
  +I<My-Header> you should call:
  +
  +  use Apache::RequestRec ();
  +  use APR::Table;
  +  $r->headers_out->set(My-Header => "SomeValue");
  +
  +If you are inside a registry script L<you can still
  +access|docs::2.0::user::coding::coding/Getting_the_C__r__Object> the
  +C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> object.
  +
  +Howerever you can choose a slower method of generating headers by just
  +printing them out before printing any response. This will work only if
  +C<L<PerlOptions
  ++ParseHeaders|docs::2.0::user::config::config/C_ParseHeaders_>> is
  +in effect. For example:
  +
  +   print "Content-type: text/html\n";
  +   print "My-Header: SomeValue\n";
  +   print "\n";
  +
  +This method is slower since Apache needs to parse the text to identify
  +certain headers it needs to know about. It also has several
  +limitations which we will now discuss.
  +
  +When using this approach you must make sure that the C<STDOUT>
  +filehandle is not set to flush the data after each print (which is set
  +by the value of a special perl variable C<$|>). Here we assume that
  +STDOUT is the currently C<select()>ed filehandle and C<$|> affects it.
  +
  +For example this code won't work:
  +
  +   local $| = 1;
  +   print "Content-type: text/html\n";
  +   print "My-Header: SomeValue\n";
  +   print "\n";
  +
  +Having a true C<$|> causes the first print() call to flush its data
  +immediately, which is sent to the internal HTTP header parser, which
  +will fail since it won't see the terminating C<"\n\n">. One solution
  +is to make sure that STDOUT won't flush immediately, like so:
  +
  +   local $| = 0;
  +   print "Content-type: text/html\n";
  +   print "My-Header: SomeValue\n";
  +   print "\n";
  +
  +Notice that we C<local()>ize that change, so it L<won't affect any
  +other
  +code|docs::general::perl_reference::perl_reference/The_Scope_of_the_Special_Perl_Variables>.
  +
  +If you send headers line by line and their total length is bigger than
  +8k, you will have the header parser problem again, since mod_perl will
  +flush data when the 8k buffer gets full. In which case the solution is
  +not to print the headers one by one, but to buffer them all in a
  +variable and then print the whole set at once.
  +
  +Notice that you don't have any of these problems with mod_cgi, because
  +it ignores any of the flush attempts by Perl. mod_cgi simply opens a
  +pipe to the external process and reads any output sent from that
  +process at once.
  +
  +If you use C<$r> to set headers as explained at the beginning of this
  +section, you won't encounter any of these problems.
  +
  +Finally, If you don't want Apache to send its own headers and you want
  +to send your own set of headers (non-parsed headers handlers) use
  +explain the
  +C<L<$r-E<gt>assbackwards|docs::2.0::api::Apache::RequestRec/C_assbackwards_>>
  +method. Notice that registry handlers will do that for you if the
  +script's name start with the C<nph-> prefix.
  +
  +
  +=head3 Forcing HTTP Response Headers Out
   
   Apache 2.0 doesn't provide a method to force HTTP response headers
   sending (what used to be done by C<send_http_header()> in Apache
   1.3). HTTP response headers are sent as soon as the first bits of the
   response body are seen by the special core output filter that
  -generates these headers. When the response handler send the first
  +generates these headers. When the response handler sends the first
   chunks of body it may be cached by the mod_perl internal buffer or
   even by some of the output filters. The response handler needs to
  -flush in order to tell all the components participating in the sending
  -of the response to pass the data out.
  +flush the output in order to tell all the components participating in
  +the sending of the response to pass the data out.
   
   For example if the handler needs to perform a relatively long-running
   operation (e.g. a slow db lookup) and the client may timeout if it
  @@ -230,11 +319,14 @@
     }
   
   If this doesn't work, check whether you have configured any
  -third-party output filters for the resource in question. Improperly
  -written filter may ignore the orders to flush the data.
  +third-party output filters for the resource in question. L<Improperly
  +written
  +filter|docs::2.0::user::handlers::filters/Writing_Well_Behaving_Filters>
  +may ignore the command to flush the data.
  +
  +
  +
   
  -META: add a link to the notes on how to write well-behaved filters
  -at handlers/filters
   
   =head2 Sending HTTP Response Body
   
  @@ -246,11 +338,17 @@
   the issues is that the HTTP response filters are not setup before the
   response phase.
   
  +
  +
  +
   =head1 Perl Specifics in the mod_perl Environment
   
   In the following sections we discuss the specifics of Perl behavior
   under mod_perl.
   
  +
  +
  +
   =head2 Request-localized Globals
   
   mod_perl 2.0 provides two types of C<SetHandler> handlers:
  @@ -295,6 +393,87 @@
   
   You can still call C<CORE::exit> to kill the interpreter, again if you
   know what you are doing.
  +
  +
  +
  +
  +=head1 C<ModPerl::Registry> Handlers Family
  +
  +=head2 A Look Behind the Scenes
  +
  +If you have a CGI script F<test.pl>:
  +
  +  #!/usr/bin/perl
  +  print "Content-type: text/plain\n\n";
  +  print "Hello";
  +
  +a typical registry family handler turns it into something like:
  +
  +  package foo_bar_baz;
  +  sub handler {
  +      local $0 = "/full/path/to/test.pl";
  +  #line 1 test.pl
  +      #!/usr/bin/perl
  +      print "Content-type: text/plain\n\n";
  +      print "Hello";
  +  }
  +
  +Turning it into an almost full-fledged mod_perl handler. The only
  +difference is that it handles the return status for you. (META: more
  +details on return status needed.)
  +
  +It then executes it as:
  +
  +  foo_bar_baz::handler($r);
  +
  +passing the C<L<$r|docs::2.0::api::Apache::RequestRec>> object as the
  +only argument to the C<handler()> function.
  +
  +Depending on the used registry handler the package is made of the file
  +path, the uri or anything else. Check the handler's documentation to
  +learn which method is used.
  +
  +
  +
  +=head2 Getting the C<$r> Object
  +
  +As explained in L<A Look Behind the Scenes|/A_Look_Behind_the_Scenes>
  +the C<$r> object is always passed to the registry script's special
  +function C<handler> as the first and the only argument, so you can get
  +this object by accessing C<@_>, since:
  +
  +  my $r = shift;
  +  print "Content-type: text/plain\n\n";
  +  print "Hello";
  +
  +is turned into:
  +
  +  sub handler {
  +      my $r = shift;
  +      print "Content-type: text/plain\n\n";
  +      print "Hello";
  +  }
  +
  +behind the scenes. Now you can use C<$r> to call various mod_perl
  +methods, e.g. rewriting the script as:
  +
  +  my $r = shift;
  +  $r->content_type('text/plain');
  +  $r->print();
  +
  +If you are deep inside some code and can't get to the entry point to
  +reach for C<$r>, you can use
  +C<L<Apache-E<gt>request|docs::2.0::api::Apache::RequestUtil/C_request_>>.
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
   
   
   =head1 Threads Coding Issues Under mod_perl
  
  
  

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


Mime
View raw message