Return-Path: 
 <docs-cvs-return-928-apmail-perl-docs-cvs-archive=perl.apache.org@perl.apache.org>
Delivered-To: apmail-perl-docs-cvs-archive@perl.apache.org
Received: (qmail 43959 invoked by uid 500); 5 Jun 2002 10:25:08 -0000
Mailing-List: contact docs-cvs-help@perl.apache.org; run by ezmlm
Precedence: bulk
List-Post: <mailto:docs-cvs@perl.apache.org>
List-Help: <mailto:docs-cvs-help@perl.apache.org>
List-Unsubscribe: <mailto:docs-cvs-unsubscribe@perl.apache.org>
List-Subscribe: <mailto:docs-cvs-subscribe@perl.apache.org>
Delivered-To: mailing list docs-cvs@perl.apache.org
Received: (qmail 43948 invoked by uid 500); 5 Jun 2002 10:25:07 -0000
Delivered-To: apmail-modperl-docs-cvs@apache.org
Date: 5 Jun 2002 10:25:06 -0000
Message-ID: <20020605102506.5258.qmail@icarus.apache.org>
From: stas@apache.org
To: modperl-docs-cvs@apache.org
Subject: cvs commit: modperl-docs/src/docs/2.0/user/compat compat.pod
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N

stas        2002/06/05 03:25:06

  Modified:    src/docs/2.0/user/compat compat.pod
  Log:
  - documenting log functions changes and a few other recent compat changes
  - polishing the doc
  
  Revision  Changes    Path
  1.23      +168 -76   modperl-docs/src/docs/2.0/user/compat/compat.pod
  
  Index: compat.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/compat/compat.pod,v
  retrieving revision 1.22
  retrieving revision 1.23
  diff -u -r1.22 -r1.23
  --- compat.pod	4 Jun 2002 10:16:44 -0000	1.22
  +++ compat.pod	5 Jun 2002 10:25:06 -0000	1.23
  @@ -163,7 +163,7 @@
   =back
   
   See the manpages of the respective modules to figure out which
  -constants they provide. (XXX: the manpages don't exist)
  +constants they provide. (XXX: not all manpages exist yet.)
   
   META: add the info how to perform the transition. XXX: may be write a
   script, which can tell you how to port the constants to 2.0? Currently
  @@ -175,13 +175,34 @@
   
   
   
  -=head1 C<Apache::>
  +=head1 C<Apache::> Methods
   
  +=head2 C<Apache-E<gt>request>
   
  +C<Apache-E<gt>request> is deprecated.  It's error-prone and hurts
  +performance when using threaded MPMs, since it has to use thread local
  +storage.
   
  -=head2 C<Apache-E<gt>define()>
  +For any location that uses C<Apache-E<gt>request> and uses
  +C<"modperl"> handler, you need to configure:
  +
  +  <Location ...>
  +      SetHandler modperl
  +      PerlOptions +GlobalRequest
  +      ...
  +  </Location>
  +
  +It's already enabled for:
   
  -C<Apache-E<gt>define()> has been replaced with
  +  <Location ...>
  +      SetHandler perl-script
  +      ...
  +  </Location>
  +
  +
  +=head2 C<Apache-E<gt>define>
  +
  +C<Apache-E<gt>define> has been replaced with
   C<Apache::exists_config_define()> residing inside
   C<Apache::ServerUtil>.
   
  @@ -195,22 +216,52 @@
   
   See the C<L<ModPerl::Util>> manpage.
   
  -=head2 C<gensym()>
  +=head2 C<Apache::gensym()>
   
   Since Perl 5.6.1 filehandlers are autovivified and there is no need
   for C<Apache::gensym()> function, since now it can be done with:
   
     open my $fh, "foo" or die $!;
   
  -Though the C function modperl_perl_gensym() is available for XS/C
  +Though the C function C<modperl_perl_gensym()> is available for XS/C
   extensions writers.
   
  -=head2 C<module()>
  +=head2 C<Apache::module()>
   
  -C<Apache::module> has been replaced with the function
  +C<Apache::module()> has been replaced with the function
   C<Apache::Module::loaded()>, which now accepts a single argument: the
   module name.
   
  +=head2 C<Apache::log_error()>
  +
  +C<Apache::log_error()> is not available in mod_perl 2.0 API. You can
  +use:
  +
  +  Apache->server->log_error
  +
  +instead. See the C<L<Apache::Log>> manpage.
  +
  +
  +
  +
  +
  +=head1 Server Object Methods
  +
  +=head2 C<$s-E<gt>register_cleanup>
  +
  +C<$s-E<gt>register_cleanup> has been replaced with
  +C<APR::Pool::cleanup_register()> which accepts the pool object as the
  +first argument instead of the server object. e.g.:
  +
  +  sub cleanup_callback { my $data = shift; ... }
  +  $s->pool->cleanup_register(\&cleanup_callback, $data);
  +
  +where the last argument C<$data> is optional, and if supplied will be
  +passed as the first argument to the callback function.
  +
  +See the C<L<APR::Pool>> manpage.
  +
  +
   
   
   
  @@ -218,22 +269,30 @@
   =head1 Request Object Methods
   
   
  -=head2 C<$r-E<gt>lookup_file>, C<$r-E<gt>lookup_uri>, 
  +=head2 C<$r-E<gt>lookup_file>
  +
  +See the next item
  +
  +=head2 C<$r-E<gt>lookup_uri>
  +
  +C<$r-E<gt>lookup_file> and C<$r-E<gt>lookup_uri> didn't change their
  +functionality but moved into C<L<Apache::SubRequest>>. Before using
  +them, add:
  +
  +  use Apache::SubRequest;
   
  -These functions have moved but didn't change their functionality. In
  -order to use them load the module they belong to in mod_perl 2.0:
   
  -  $r->lookup_file          Apache::SubRequest
  -  $r->lookup_uri           Apache::SubRequest
  +=head2 C<$r-E<gt>content>
   
  +See the next item.
   
  -=head2 C<$r-E<gt>content()> and C<$r-E<gt>args()> in an Array Context
  +=head2 C<$r-E<gt>args> in an Array Context
   
  -C<$r-E<gt>args()> in 2.0 returns the query string without parsing and
  +C<$r-E<gt>args> in 2.0 returns the query string without parsing and
   splitting it into an array. You can also set the query string by
   passing a string to this method.
   
  -C<$r-E<gt>content()> and C<$r-E<gt>args()> in an array context were
  +C<$r-E<gt>content> and C<$r-E<gt>args> in an array context were
   mistakes that never should have been part of the mod_perl 1.0
   API. There multiple reason for that, among others:
   
  @@ -270,30 +329,31 @@
   
   =back
   
  -Instead you should use C<Apache::Request>'s params() and similar
  -methods to do the parsing for you. See the L<Apache::Request> manpage.
  +Instead you should use C<Apache::Request>'s C<params()> and similar
  +methods to do the parsing for you. See the C<L<Apache::Request>>
  +manpage.
   
   XXX: ...when Apache::Request will be ported to 2.0. For now you can
   use the code in C<Apache::compat> that implements these methods in
   Perl.
   
  -=head2  C<chdir_file()>
  +=head2  C<$r-E<gt>chdir_file>
   
  -C<chdir()> is not a thread-safe function, therefore C<chdir_file()> is
  -gone from the API.
  +C<chdir()> is not a thread-safe function, therefore
  +C<$r-E<gt>chdir_file> is gone from the API.
   
   =head2 C<$r-E<gt>connection-E<gt>user>
   
  -This method is deprecated in 1.0 and C<$r-E<gt>user> should be used
  -instead for both versions of mod_perl. C<Apache::user()> method is
  -available since mod_perl version 1.24_01.
  +This method is deprecated in mod_perl 1.0 and C<$r-E<gt>user> should
  +be used instead, for both versions of mod_perl. C<$r-E<gt>user()>
  +method is available since mod_perl version 1.24_01.
   
  -=head2 C<$r-E<gt>is_main()>
  +=head2 C<$r-E<gt>is_main>
   
  -C<$r-E<gt>is_main()> is not part of the mod_perl 2.0 API. Use
  -C<!$r-E<gt>main()> instead.
  +C<$r-E<gt>is_main> is not part of the mod_perl 2.0 API. Use
  +C<!$r-E<gt>main> instead.
   
  -=head2 C<$r-E<gt>finfo()>
  +=head2 C<$r-E<gt>finfo>
   
   XXX: not implemented yet. To be implemented. C<Apache::compat> handles
   that for now with:
  @@ -304,7 +364,15 @@
         \*_;
     }
   
  -=head2 C<$r-E<gt>header_in()>, C<$r-E<gt>header_out()> and C<$r-E<gt>err_header_out()>
  +=head2 C<$r-E<gt>header_in>
  +
  +See the next item.
  +
  +=head2 C<$r-E<gt>header_out>
  +
  +See the next item.
  +
  +=head2 C<$r-E<gt>err_header_out>
   
   C<header_in()>, C<header_out()> and C<err_header_out()> are not
   available in 2.0. Use C<headers_in()>, C<headers_out()> and
  @@ -320,56 +388,42 @@
   See the L<Apache::RequestRec> manpage.
   
   
  +=head2 C<$r-E<gt>log_reason>
   
  +C<$r-E<gt>log_reason> is not available in mod_perl 2.0 API. Use the
  +other standard logging functions provided by the C<L<Apache::Log>>
  +module. For example:
   
  -=head2 C<$r-E<gt>log_reason()>
  -
  -C<log_reason()> has been replaced with a set of dedicated functions:
  -C<Apache::RequestRec::log_error()>, C<Apache::ServerRec::log_error()>,
  -C<Apache::Log::info()> and others.
  +  $r->log_error("it works!");
   
  -See the L<Apache::RequestRec>, L<Apache::Server> and L<Apache::Log>
  -manpages.
  +See the C<L<Apache::Log>> manpage.
   
   
  -=head2 C<$r-E<gt>register_cleanup()>
  +=head2 C<$r-E<gt>register_cleanup>
   
  -register_cleanup() has been replaced with
  +C<$r-E<gt>register_cleanup> has been replaced with
   C<APR::Pool::cleanup_register()> which accepts the pool object as the
   first argument instead of the request object. e.g.:
   
  -  $r->pool->cleanup_register(\&cleanup, $data);
  +  sub cleanup_callback { my $data = shift; ... }
  +  $r->pool->cleanup_register(\&cleanup_callback, $data);
   
  -where the last argument C<$data> is optional.
  +where the last argument C<$data> is optional, and if supplied will be
  +passed as the first argument to the callback function.
   
   See the L<APR::Pool> manpage.
   
   
  -=head2 C<$r-E<gt>request()>
  +=head2 C<$r-E<gt>request>
   
  -Use C<Apache::request()>.
  +Use C<Apache-E<gt>request>.
   
  -Notice that C<Apache-E<gt>request> is deprecated.  It's error-prone
  -and hurts performance when using threaded MPMs, since it has to use
  -thread local storage.
   
  -For any location that uses C<Apache-E<gt>request> and uses
  -C<"modperl"> handler, you need to configure:
  +=head2 C<$r-E<gt>send_fd>
   
  -  <Location ...>
  -      SetHandler modperl
  -      PerlOptions +GlobalRequest
  -      ...
  -  </Location>
  -
  -It's already enabled for:
  -
  -  <Location ...>
  -      SetHandler perl-script
  -      ...
  -  </Location>
  +See the next item.
   
  -=head2 C<$r-E<gt>send_fd()> and C<$r-E<gt>send_fd_length()>
  +=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 the its functionality. See the
  @@ -385,10 +439,22 @@
   
   See the L<Apache::ServerUtil> manpage.
   
  -=head2 C<$r-E<gt>hard_timeout()>, C<$r-E<gt>reset_timeout()>, C<$r-E<gt>soft_timeout()> and C<$r-E<gt>kill_timeout()>
  +=head2 C<$r-E<gt>hard_timeout>
   
  -The functions C<$r-E<gt>hard_timeout()>, C<$r-E<gt>reset_timeout()>,
  -C<$r-E<gt>soft_timeout()> and C<$r-E<gt>kill_timeout()> aren't needed
  +See the next item.
  +
  +=head2 C<$r-E<gt>reset_timeout>
  +
  +See the next item.
  +
  +=head2 C<$r-E<gt>soft_timeout>
  +
  +See the next item.
  +
  +=head2 C<$r-E<gt>kill_timeout>
  +
  +The functions C<$r-E<gt>hard_timeout>, C<$r-E<gt>reset_timeout>,
  +C<$r-E<gt>soft_timeout> and C<$r-E<gt>kill_timeout> aren't needed
   in mod_perl 2.0.
   
   
  @@ -397,8 +463,8 @@
   
   =head1 Apache::File
   
  -The methods from module C<Apache::File> have been either moved to
  -other packages or removed.
  +The methods from mod_perl 1.0's module C<Apache::File> have been
  +either moved to other packages or removed.
   
   =head2 C<open()> and C<close()>
   
  @@ -417,9 +483,29 @@
   mtime() now belongs to the module L<Apache::RequestRec>.
   
   
  -=head2 C<discard_request_body()>, C<meets_conditions()>, C<set_content_length()>, C<set_etag()>, C<set_last_modified()> and C<update_mtime()>
  +=head2 C<discard_request_body()>
  +
  +This function now belongs to the module C<L<Apache::Response>>.
  +
  +=head2 C<meets_conditions()>
  +
  +This function now belongs to the module C<L<Apache::Response>>.
   
  -These functions now belong to the module L<Apache::Response>.
  +=head2 C<set_content_length()>
  +
  +This function now belongs to the module C<L<Apache::Response>>.
  +
  +=head2 C<set_etag()>
  +
  +This function now belongs to the module C<L<Apache::Response>>.
  +
  +=head2 C<set_last_modified()>
  +
  +This function now belongs to the module C<L<Apache::Response>>.
  +
  +=head2 C<update_mtime()>
  +
  +This function now belongs to the module C<L<Apache::Response>>.
   
   
   
  @@ -430,11 +516,11 @@
   
   A few C<Apache::Util> functions have changed their interface.
   
  -=head2 C<Apache::Util::size_string>
  +=head2 C<Apache::Util::size_string()>
   
  -C<Apache::Util::size_string> has been replaced with
  -C<APR::String::format_size>, which returns formatted strings of only 4
  -characters long. See the C<L<APR::String>> manpage.
  +C<Apache::Util::size_string()> has been replaced with
  +C<APR::String::format_size()>, which returns formatted strings of only
  +4 characters long. See the C<L<APR::String>> manpage.
   
   =head2 C<Apache::Util::unescape_uri()>
   
  @@ -480,11 +566,17 @@
   
   See the I<attributes> manpage.
   
  -mod_perl 2.0 doesn't support the C<($$)> prototypes, mainly because
  -several callbacks in 2.0 have more arguments than C<$r>, so the
  -C<($$)> prototype doesn't make sense anymore. Therefore if you want
  -your code to work with both mod_perl generations, you should use the
  -subroutine attributes.
  +mod_perl 2.0 doesn't handles callbacks with C<($$)> prototypes
  +differently than other callbacks (as it did in mod_perl 1.0), mainly
  +because several callbacks in 2.0 have more arguments than just C<$r>,
  +so the C<($$)> prototype doesn't make sense anymore. Therefore if you
  +want your code to work with both mod_perl generations and you can
  +allow the luxury of:
  +
  +  require 5.6.0;
  +
  +you should use the subroutine attributes. The subroutine attributes
  +are supported in Perl only since version 5.6.0.
   
   
   
  
  
  

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