← Back to branch summary

~ubuntu-branches/ubuntu/edgy/libapache2-mod-perl2/edgy-updates

« back to all changes in this revision

Viewing changes to docs/user/porting/compat.pod

  • Committer: Bazaar Package Importer
  • Author(s): Adam Conrad
  • Date: 2004-08-19 06:23:48 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20040819062348-jxl4koqbtvgm8v2t
Tags: 1.99.14-4
Remove the LFS CFLAGS, and build-dep against apache2-*-dev (>= 2.0.50-10)
as we're backing out of the apache2/apr ABI transition.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/user/porting/compat.pod
117
117
=back
118
118
 
119
119
 
 
120
=head1 Server Startup
 
121
 
 
122
mod_perl 1.0 was always running its startup code immediately at the
 
123
server startup. On a big setup it was causing a slow startup, since
 
124
Apache always starts and immediately restarts itself, running the
 
125
startup code twice. Therefore in mod_perl 2.0, by default perl won't
 
126
be started until after the configuration phase. So, if for example you
 
127
run:
 
128
 
 
129
  % apachectl configtest
 
130
 
 
131
none of your perl code will be executed.
 
132
 
 
133
There are two cases when mod_perl 2.0 is forced to start early. First,
 
134
is when
 
135
C<L<PerlLoadModule|docs::2.0::user::config::config/C_PerlLoadModule_>>
 
136
is used and the second is
 
137
C<L<E<lt>PerlE<gt>|docs::2.0::api::Apache::PerlSections>> sections,
 
138
both requiring a running perl, and triggering an early server startup.
 
139
 
 
140
Therefore at the moment, if you want to trigger an early startup, like
 
141
mod_perl 1.0 does, just add an empty
 
142
C<L<E<lt>PerlE<gt>|docs::2.0::api::Apache::PerlSections>> section:
 
143
 
 
144
  <Perl>
 
145
  # trigger an early startup
 
146
  </Perl>
 
147
 
 
148
Right after loading the mod_perl module in F<httpd.conf> if you are
 
149
using DSO, or just before your mod_perl configuration if you using a
 
150
static build.
 
151
 
 
152
 
120
153
=head1 Code Porting
121
154
 
122
155
mod_perl 2.0 is trying hard to be back compatible with mod_perl
401
434
 
402
435
=head2 C<$ENV{GATEWAY_INTERFACE}>
403
436
 
404
 
The environment variable C<$ENV{GATEWAY_INTERFACE}> is deprecated in
405
 
mod_perl 2.0 (See:
406
 
C<L<MP_COMPAT_1X=0|docs::2.0::user::install::install/MP_COMPAT_1X>>). Instead
407
 
use C<$ENV{MOD_PERL}> (available in both mod_perl generations), which
408
 
is set to something like this:
 
437
The environment variable C<$ENV{GATEWAY_INTERFACE}> is not special in
 
438
mod_perl 2.0, but the same as any other CGI environment variables,
 
439
i.e. it'll be enabled only if C<L<PerlOptions
 
440
+SetupEnv|docs::2.0::user::config::config/C_SetupEnv_>> is enabled and
 
441
its value would be the default:
 
442
 
 
443
  CGI/1.1
 
444
 
 
445
or anything else Apache decides to set it to, but not:
 
446
 
 
447
  CGI-Perl/1.1
 
448
 
 
449
Instead use C<$ENV{MOD_PERL}> (available in both mod_perl
 
450
generations), which is set to the mod_perl version, like so:
409
451
 
410
452
  mod_perl/1.99_03-dev
411
453
 
412
 
However to check the version it's better to use C<$mod_perl::VERSION>:
 
454
Therefore in order to check whether you are running under mod_perl,
 
455
you'd say:
 
456
 
 
457
  if ($ENV{MOD_PERL}) { ... }
 
458
 
 
459
To check for a specific version it's better to use
 
460
C<$mod_perl::VERSION>:
413
461
 
414
462
  use mod_perl;
415
463
  use constant MP2 => ($mod_perl::VERSION >= 1.99);
583
631
C<Apache-E<gt>set_handlers> is avalable via
584
632
C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
585
633
 
 
634
To reset the list of handlers, instead of doing:
 
635
 
 
636
  $r->set_handlers(PerlAuthenHandler => [ \&OK ]);
 
637
 
 
638
do:
 
639
 
 
640
  $r->set_handlers(PerlAuthenHandler => []);
 
641
 
 
642
or
 
643
 
 
644
  $r->set_handlers(PerlAuthenHandler => undef);
 
645
 
 
646
See
 
647
C<L<Apache::RequestUtil|docs::2.0::api::Apache::RequestUtil/C_set_handlers_>>.
 
648
 
 
649
 
586
650
=head2 C<Apache-E<gt>httpd_conf>
587
651
 
588
652
C<Apache-E<gt>httpd_conf> is now C<$s-E<gt>add_config> or
597
661
C<Apache-E<gt>httpd_conf> is avalable via
598
662
C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
599
663
 
 
664
 
 
665
 
600
666
=head2 C<Apache::exit()>
601
667
 
602
 
C<Apache::exit()> has been replaced with C<ModPerl::Util::exit()>,
603
 
which is a function (not a method) and accepts a single optional
604
 
argument: status, whose default is 0 (== do nothing).
605
 
 
606
 
See the
607
 
C<L<ModPerl::Util|docs::2.0::api::ModPerl::Util>>
608
 
manpage.
 
668
C<Apache::exit()> has been replaced with
 
669
C<L<ModPerl::Util::exit()|docs::2.0::api::ModPerl::Util/C_exit_>>.
 
670
 
 
671
 
609
672
 
610
673
=head2 C<Apache::gensym()>
611
674
 
729
792
C<L<Apache::compat|docs::2.0::api::Apache::compat>> implements
730
793
C<$r-E<gt>current_callback> for backwards compatibility.
731
794
 
 
795
=head2 C<$r-E<gt>cleanup_for_exec>
 
796
 
 
797
C<$r-E<gt>cleanup_for_exec> wasn't a part of the mp1 core API, but
 
798
lived in a 3rd party module C<Apache::SubProcess>. That module's
 
799
functionality is now a part of mod_perl 2.0 API. But Apache 2.0
 
800
doesn't need this function any longer.
 
801
 
 
802
C<L<Apache::compat|docs::2.0::api::Apache::compat>> implements
 
803
C<$r-E<gt>cleanup_for_exec> for backwards compatibility as a NOOP.
 
804
 
 
805
See also the
 
806
C<L<Apache::SubProcess|docs::2.0::api::Apache::SubProcess>> manpage.
 
807
 
732
808
=head2 C<$r-E<gt>get_remote_host>
733
809
 
734
810
C<get_remote_host()> is now invoked on the C<L<connection
740
816
C<$r-E<gt>get_remote_host> is available through
741
817
C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
742
818
 
743
 
=head2 C<$r-E<gt>cleanup_for_exec>
744
 
 
745
 
C<$r-E<gt>cleanup_for_exec> doesn't exist in the Apache 2.0 API, it is
746
 
now being internally called by the Apache process spawning
747
 
functions. For more information see
748
 
C<L<Apache::SubProcess|docs::2.0::api::Apache::SubProcess>> manpage.
749
 
 
750
 
There is C<L<$pool-E<gt>cleanup_for_exec|docs::2.0::api::APR::Pool>>,
751
 
but it's not the same as C<$r-E<gt>cleanup_for_exec> in the mod_perl
752
 
1.0 API.
753
 
 
754
819
 
755
820
=head2 C<$r-E<gt>content>
756
821
 
862
927
 
863
928
=head2 C<$r-E<gt>notes>
864
929
 
865
 
Similar to C<headers_in()>, C<headers_out()> and C<err_headers_out()>
866
 
in mod_perl 2.0, C<$r-E<gt>notes()> returns an
 
930
Similar to
 
931
C<L<headers_in()|docs::2.0::api::Apache::RequestRec/C_headers_in_>>,
 
932
C<L<headers_out()|docs::2.0::api::Apache::RequestRec/C_headers_out_>>
 
933
and
 
934
C<L<err_headers_out()|docs::2.0::api::Apache::RequestRec/C_err_headers_out_>>
 
935
in mod_perl 2.0, C<L<$r-E<gt>notes()|docs::2.0::api::Apache::RequestRec/C_notes_>> returns an
867
936
C<L<APR::Table|docs::2.0::api::APR::Table>> object, which can be used
868
 
as a tied hash or calling its I<get()>/I<set()>/I<add()>/I<unset()>
869
 
methods.
 
937
as a tied hash or calling its
 
938
I<L<get()|docs::2.0::api::APR::Table/C_get_>> /
 
939
I<L<set()|docs::2.0::api::APR::Table/C_set_>> /
 
940
I<L<add()|docs::2.0::api::APR::Table/C_add_>> /
 
941
I<L<unset()|docs::2.0::api::APR::Table/C_unset_>> methods.
870
942
 
871
943
It's also possible to adjust the mod_perl 1.0 code using
872
 
Apache::compat's
 
944
C<L<Apache::compat|docs::2.0::api::Apache::compat>>'s
873
945
L<overriding|docs::2.0::api::Apache::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>:
874
946
 
875
947
   use Apache::compat;
986
1058
  # during startup
987
1059
  my $conf_dir = Apache::server_root_relative($s->pool, 'conf');
988
1060
 
989
 
The old way:
990
 
 
991
 
  my $conf_dir = Apache::server_root_relative('Apache', 'conf');
992
 
 
993
 
will work as well, but you shouldn't use it, because it'll internally
994
 
use a global pool, which is a bit slower, but the worst drawback is
995
 
that every time you use this way the allocated from this pool memory
996
 
won't be cleaned up, till the server quits so there will be a memory
997
 
leak. When you are inside a request and use C<$r-E<gt>pool>, this pool
998
 
is freed at the end of each request.
 
1061
Alternatively:
 
1062
 
 
1063
  # during request
 
1064
  my $conf_dir = $r->server_root_relative('conf');
 
1065
  # during startup
 
1066
  my $conf_dir = $c->server_root_relative('conf');
 
1067
 
 
1068
Note that the old form
 
1069
 
 
1070
  my $conf_dir = Apache->server_root_relative('conf');
 
1071
 
 
1072
is no longer valid - C<Apache::server_root_relative> must be called
 
1073
from either one of C<$r>, C<$s>, or C<$c>, or be explicitly
 
1074
passed a pool.
999
1075
 
1000
1076
 
1001
1077
See the L<Apache::ServerUtil> manpage.
1016
1092
=head2 C<$r-E<gt>kill_timeout>
1017
1093
 
1018
1094
The functions C<$r-E<gt>hard_timeout>, C<$r-E<gt>reset_timeout>,
1019
 
C<$r-E<gt>soft_timeout> and C<$r-E<gt>kill_timeout> aren't needed
1020
 
in mod_perl 2.0.
 
1095
C<$r-E<gt>soft_timeout> and C<$r-E<gt>kill_timeout> aren't needed in
 
1096
mod_perl 2.0.  C<L<Apache::compat|docs::2.0::api::Apache::compat>>
 
1097
implements these functions for backwards compatibility as NOOPs.
 
1098
 
1021
1099
 
1022
1100
=head2 C<$r-E<gt>set_byterange>
1023
1101
 
1168
1246
 
1169
1247
=head2 C<Apache::Util::ht_time()>
1170
1248
 
1171
 
C<Apache::Util::ht_time()> has been replaced (temporary?) with
1172
 
C<Apache::Util::format_time()>, which requires a pool object as a
1173
 
forth argument. All four arguments are now required.
 
1249
C<Apache::Util::ht_time()> now requires a
 
1250
C<L<pool|docs::2.0::api::APR::Pool>> object as a first argument.
1174
1251
 
1175
1252
For example:
1176
1253
 
1177
1254
   use Apache::Util ();
1178
1255
   $fmt = '%a, %d %b %Y %H:%M:%S %Z';
1179
1256
   $gmt = 1;
1180
 
   $fmt_time = Apache::Util::format_time(time(), $fmt, $gmt, $r->pool);
1181
 
 
1182
 
See the L<Apache::Util> manpage.
 
1257
   $fmt_time = Apache::Util::ht_time($r->pool, time(), $fmt, $gmt);
 
1258
 
 
1259
See the L<Apache::Util|docs::2.0::api::Apache::Util> manpage.
 
1260
 
 
1261
It's also possible to adjust the mod_perl 1.0 code using
 
1262
Apache::compat's
 
1263
L<overriding|docs::2.0::api::Apache::compat/Compatibility_Functions_Colliding_with_mod_perl_2_0_API>.
 
1264
 
 
1265
For example:
 
1266
 
 
1267
  use Apache::compat;
 
1268
  Apache::compat::override_mp2_api('Apache::Util::ht_time');
 
1269
  $fmt_time = Apache::Util::ht_time(time(), $fmt, $gmt);
 
1270
  Apache::compat::restore_mp2_api('Apache::Util::ht_time');
1183
1271
 
1184
1272
 
1185
1273
=head2 C<Apache::Util::validate_password()>
1327
1415
handlers are configured, respecting (or ignoring) the return 
1328
1416
value of each handler as it is called.
1329
1417
 
1330
 
See L<Single Phase's Multiple Handlers
1331
 
Behavior|docs::2.0::user::handlers::intro/Single_Phase_s_Multiple_Handlers_Behavior>
1332
 
for a complete description of each hook and its run-type.
 
1418
See L<Stacked
 
1419
Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> for a
 
1420
complete description of each hook and its run-type.
 
1421
 
1333
1422
 
1334
1423
 
1335
1424
=head1 C<Apache::src>