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/porting compat.pod
Date Wed, 17 Dec 2003 21:04:12 GMT
stas        2003/12/17 13:04:12

  Modified:    src/docs/2.0/api/Apache compat.pod
               src/docs/2.0/user/porting compat.pod
  Log:
  - document the new overridable mechanism in Apache::compat
  - document the four new overridable functions in Apache::compat (2
  existed before but now not enabled by default)
  - mention the new APR::Finfo class
  
  Revision  Changes    Path
  1.5       +91 -3     modperl-docs/src/docs/2.0/api/Apache/compat.pod
  
  Index: compat.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/compat.pod,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -u -r1.4 -r1.5
  --- compat.pod	11 Apr 2003 03:20:08 -0000	1.4
  +++ compat.pod	17 Dec 2003 21:04:12 -0000	1.5
  @@ -1,8 +1,8 @@
  -=head1 NAME
  +=head1 Name
   
   Apache::compat -- 1.0 backward compatibility functions deprecated in 2.0
   
  -=head1 SYNOPSIS
  +=head1 Synopsis
   
     # either add at the very beginning of startup.pl
     use Apache2
  @@ -11,7 +11,12 @@
     PerlModule Apache2
     PerlModule Apache::compat
   
  -=head1 DESCRIPTION
  +  # override and restore compat functions colliding with mp2 API
  +  Apache::compat::override_mp2_api('Apache::Connection::local_addr');
  +  my ($local_port, $local_addr) = sockaddr_in($c->local_addr);
  +  Apache::compat::restore_mp2_api('Apache::Connection::local_addr');
  +
  +=head1 Description
   
   C<Apache::compat> provides mod_perl 1.0 compatibility layer and can be
   used to smooth the transition process to mod_perl 2.0.
  @@ -29,6 +34,89 @@
   to L<port your
   code|docs::2.0::user::porting::porting> not to use deprecated
   functions and stop using the compatibility layer.
  +
  +
  +
  +
  +
  +
  +=head1 Compatibility Functions Colliding with mod_perl 2.0 API
  +
  +Most of the functions provided by Apache::compat don't interfere with
  +mod_perl 2.0 API. However there are several functions which have the
  +same name in the mod_perl 1.0 and mod_perl 2.0 API, accept the same
  +number of arguments, but either the arguments themselves aren't the
  +same or the return values are different. For example the mod_perl 1.0
  +code:
  +
  +  require Socket;
  +  my $sockaddr_in = $c->local_addr;
  +  my ($local_port, $local_addr) = Socket::sockaddr_in($sockaddr_in);
  +
  +should be adjusted to be:
  +
  +  require Apache::Connection;
  +  require APR::SocketAddr;
  +  my $sockaddr = $c->local_addr;
  +  my ($local_port, $local_addr) = ($sockaddr->port, $sockaddr->ip_get);
  +
  +to work under mod_perl 2.0.
  +
  +As you can see in mod_perl 1.0 API local_addr() was returning a
  +SOCKADDR_IN object (see the Socket perl manpage), in mod_perl 2.0 API
  +it returns an C<L<APR::SocketAddr|docs::2.0::api::APR::SocketAddr>>
  +object, which is a totally different beast. If Apache::compat
  +overrides the function C<local_addr()> to be back-compatible with
  +mod_perl 1.0 API. Any code that relies on this function to work as it
  +should under mod_perl 2.0 will be broken. Therefore the solution is
  +not to override C<local_addr()> by default. Instead a special API is
  +provided which overrides colliding functions only when needed and
  +which can be restored when no longer needed. So for example if you
  +have code from mod_perl 1.0:
  +
  +  my ($local_port, $local_addr) = Socket::sockaddr_in($c->local_addr);
  +
  +and you aren't ready to port it to to use the mp2 API:
  +
  +  my ($local_port, $local_addr) = ($c->local_addr->port,
  +                                   $c->local_addr->ip_get);
  +
  +you could do the following:
  +
  +  Apache::compat::override_mp2_api('Apache::Connection::local_addr');
  +  my ($local_port, $local_addr) = Socket::sockaddr_in($c->local_addr);
  +  Apache::compat::restore_mp2_api('Apache::Connection::local_addr');
  +
  +Notice that you need to restore the API as soon as possible.
  +
  +Both C<override_mp2_api()> and C<restore_mp2_api()> accept a list of
  +functions to operate on.
  +
  +=head2 Available Overridable Functions
  +
  +At the moment the following colliding functions are available for
  +overriding:
  +
  +=over
  +
  +=item * C<Apache::RequestRec::notes>
  +
  +=item * C<Apache::RequestRec::finfo>
  +
  +=item * C<Apache::Connection::local_addr>
  +
  +=item * C<Apache::Connection::remote_addr>
  +
  +=back
  +
  +
  +
  +
  +
  +
  +
  +
  +
   
   =head1 Use in CPAN Modules
   
  
  
  
  1.28      +59 -18    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.27
  retrieving revision 1.28
  diff -u -u -r1.27 -r1.28
  --- compat.pod	11 Dec 2003 18:06:55 -0000	1.27
  +++ compat.pod	17 Dec 2003 21:04:12 -0000	1.28
  @@ -824,17 +824,38 @@
   
   =head2 C<$r-E<gt>finfo>
   
  -Probably won't be implemented, because Apache 2.0's finfo
  -datastructure can't be mapped into the Perl finfo datastructure.
  +As Apache 2.0 doesn't provide an access to the stat structure, but
  +hides it in the opaque object you need to use the
  +C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> accessor methods.
   
  -C<L<Apache::compat|docs::2.0::api::Apache::compat>> handles that for
  -now with:
  +It's also possible to to adjust the mod_perl 1.0 code using
  +Apache::compat's
  +L<overriding|docs::2.0::api::Apache::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>.
  +For example:
   
  -  sub finfo {
  -      my $r = shift;
  -      stat $r->filename;
  -      \*_;
  -  }
  +  use Apache::compat;
  +  Apache::compat::override_mp2_api('Apache::RequestRec::finfo');
  +  my $is_writable = -w $r->finfo;
  +  Apache::compat::restore_mp2_api('Apache::RequestRec::finfo');
  +
  +which internally does just the following:
  +
  + stat $r->filename and return \*_;
  +
  +So may be it's easier to just change the code to use this directly, so
  +the above example can be adjusted to be:
  +
  +  my $is_writable = -w $r->filename;
  +
  +with the performance penalty of an extra C<stat()> system call. If you
  +don't want this extra call, you'd have to write:
  +
  +  use APR::Finfo;
  +  use APR::Const -compile => qw(WWRITE);
  +  my $is_writable = $r->finfo->protection & APR::WWRITE,
  +
  +See the C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> manpage for more
  +information.
   
   =head2 C<$r-E<gt>notes>
   
  @@ -844,15 +865,18 @@
   as a tied hash or calling its I<get()>/I<set()>/I<add()>/I<unset()>
   methods.
   
  -If C<L<Apache::compat|docs::2.0::api::Apache::compat>> is loaded the
  -old API:
  +It's also possible to to adjust the mod_perl 1.0 code using
  +Apache::compat's
  +L<overriding|docs::2.0::api::Apache::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>:
   
  +   use Apache::compat;
  +   Apache::compat::override_mp2_api('Apache::RequestRec::notes');
      $r->notes($key => $val);
      $val = $r->notes($key);
  +   Apache::compat::restore_mp2_api('Apache::RequestRec::notes');
   
  -is supported as well.
  -
  -See the L<Apache::RequestRec> manpage.
  +See the C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>
  +manpage.
   
   =head2 C<$r-E<gt>header_in>
   
  @@ -1051,13 +1075,30 @@
   now it'll be written as:
   
     require APR::SockAddr;
  -  my $serverport = $c->local_addr->port_get;
  +  my $serverport = $c->local_addr->port;
     my $serverip   = $c->local_addr->ip_get;
  -  my $remoteport = $c->remote_addr->port_get;
  +  my $remoteport = $c->remote_addr->port;
     my $remoteip   = $c->remote_addr->ip_get;
   
  -META: it's not simple to fix this in the compat layer, since it'll
  -break the API for normal Apache 2.0 modules. Stay tuned for solutions.
  +It's also possible to to adjust the code using Apache::compat's
  +L<overriding|docs::2.0::api::Apache::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>:
  +
  +  use Socket 'sockaddr_in';
  +  use Apache::compat;
  +  
  +  Apache::compat::override_mp2_api('Apache::Connection::local_addr');
  +  my ($serverport, $serverip) = sockaddr_in($r->connection->local_addr);
  +  Apache::compat::restore_mp2_api('Apache::Connection::local_addr');
  +  
  +  Apache::compat::override_mp2_api('Apache::Connection::remote_addr');
  +  my ($remoteport, $remoteip) = sockaddr_in($r->connection->remote_addr);
  +  Apache::compat::restore_mp2_api('Apache::Connection::remote_addr');
  +
  +
  +
  +
  +
  +
   
   =head1 C<Apache::File>
   
  
  
  

---------------------------------------------------------------------
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