1docs::api::Apache2::comUpsaetr(3C)ontributed Perl Documednotcast:i:oanpi::Apache2::compat(3)
2
6 Apache2::compat -- 1.0 backward compatibility functions deprecated in
7 2.0
8
10 # either add at the very beginning of startup.pl
11 use Apache2::compat;
12 # or httpd.conf
13 PerlModule Apache2::compat
14 # override and restore compat functions colliding with mp2 API
16 Apache2::compat::override_mp2_api('Apache2::Connection::local_addr');
17 my ($local_port, $local_addr) = sockaddr_in($c->local_addr);
18 Apache2::compat::restore_mp2_api('Apache2::Connection::local_addr');
19
21 "Apache2::compat" provides mod_perl 1.0 compatibility layer and can be
22 used to smooth the transition process to mod_perl 2.0.
23 It includes functions that have changed their API or were removed in
25 mod_perl 2.0. If your code uses any of those functions, you should load
26 this module at the server startup, and everything should work as it did
27 in 1.0. If it doesn't please report the bug, but before you do that
28 please make sure that your code does work properly under mod_perl 1.0.
29 However, remember, that it's implemented in pure Perl and not C,
31 therefore its functionality is not optimized and it's the best to try
32 to port your code not to use deprecated functions and stop using the
33 compatibility layer.
34
36 Most of the functions provided by Apache2::compat don't interfere with
37 mod_perl 2.0 API. However there are several functions which have the
38 same name in the mod_perl 1.0 and mod_perl 2.0 API, accept the same
39 number of arguments, but either the arguments themselves aren't the
40 same or the return values are different. For example the mod_perl 1.0
41 code:
42 require Socket;
44 my $sockaddr_in = $c->local_addr;
45 my ($local_port, $local_addr) = Socket::sockaddr_in($sockaddr_in);
46 should be adjusted to be:
48 require Apache2::Connection;
50 require APR::SockAddr;
51 my $sockaddr = $c->local_addr;
52 my ($local_port, $local_addr) = ($sockaddr->port, $sockaddr->ip_get);
53 to work under mod_perl 2.0.
55 As you can see in mod_perl 1.0 API local_addr() was returning a
57 SOCKADDR_IN object (see the Socket perl manpage), in mod_perl 2.0 API
58 it returns an "APR::SockAddr" object, which is a totally different
59 beast. If Apache2::compat overrides the function local_addr() to be
60 back-compatible with mod_perl 1.0 API. Any code that relies on this
61 function to work as it should under mod_perl 2.0 will be broken.
62 Therefore the solution is not to override local_addr() by default.
63 Instead a special API is provided which overrides colliding functions
64 only when needed and which can be restored when no longer needed. So
65 for example if you have code from mod_perl 1.0:
66 my ($local_port, $local_addr) = Socket::sockaddr_in($c->local_addr);
68 and you aren't ready to port it to to use the mp2 API:
70 my ($local_port, $local_addr) = ($c->local_addr->port,
72 $c->local_addr->ip_get);
73 you could do the following:
75 Apache2::compat::override_mp2_api('Apache2::Connection::local_addr');
77 my ($local_port, $local_addr) = Socket::sockaddr_in($c->local_addr);
78 Apache2::compat::restore_mp2_api('Apache2::Connection::local_addr');
79 Notice that you need to restore the API as soon as possible.
81 Both override_mp2_api() and restore_mp2_api() accept a list of
83 functions to operate on.
84 Available Overridable Functions
86 At the moment the following colliding functions are available for
87 overriding:
88 Apache2::RequestRec::notes
90 Apache2::RequestRec::filename
91 Apache2::RequestRec::finfo
92 Apache2::Connection::local_addr
93 Apache2::Connection::remote_addr
94 Apache2::Util::ht_time
95 Apache2::Module::top_module
96 Apache2::Module::get_config
97 APR::URI::unparse
98
100 The short answer: Do not use "Apache2::compat" in CPAN modules.
101 The long answer:
103 "Apache2::compat" is useful during the mod_perl 1.0 code porting.
105 Though remember that it's implemented in pure Perl. In certain cases it
106 overrides mod_perl 2.0 methods, because their API is very different and
107 doesn't map 1:1 to mod_perl 1.0. So if anything, not under user's
108 control, loads "Apache2::compat" user's code is forced to use the
109 potentially slower method. Which is quite bad.
110 Some users may choose to keep using "Apache2::compat" in production and
112 it may perform just fine. Other users will choose not to use that
113 module, by porting their code to use mod_perl 2.0 API. However it
114 should be users' choice whether to load this module or not and not to
115 be enforced by CPAN modules.
116 If you port your CPAN modules to work with mod_perl 2.0, you should
118 follow the porting Perl and XS module guidelines.
119 Users that are stuck with CPAN modules preloading "Apache2::compat",
121 can prevent this from happening by adding
122 $INC{'Apache2/compat.pm'} = __FILE__;
124 at the very beginning of their startup.pl. But this will most certainly
126 break the module that needed this module.
127
129 You should be reading the mod_perl 1.0 API docs for usage of the
130 methods and functions in this package, since what this module is doing
131 is providing a backwards compatibility and it makes no sense to
132 duplicate documentation.
133 Another important document to read is: Migrating from mod_perl 1.0 to
135 mod_perl 2.0 which covers all mod_perl 1.0 constants, functions and
136 methods that have changed in mod_perl 2.0.
137
139 mod_perl 2.0 documentation.
140
142 mod_perl 2.0 and its core modules are copyrighted under The Apache
143 Software License, Version 2.0.
144
146 The mod_perl development team and numerous contributors.
147perl v5.38.0 2023-07-20 docs::api::Apache2::compat(3)