stas 2004/07/15 18:11:03
Modified: src/docs/2.0/api/Apache RequestUtil.pod ServerUtil.pod
src/docs/2.0/api/ModPerl RegistryLoader.pod
src/docs/2.0/user/handlers http.pod server.pod
src/docs/2.0/user/install install.pod
src/docs/2.0/user/performance prevent.pod
src/docs/2.0/user/porting compat.pod
Log:
sync with api changes
Revision Changes Path
1.25 +35 -0 modperl-docs/src/docs/2.0/api/Apache/RequestUtil.pod
Index: RequestUtil.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/RequestUtil.pod,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -u -r1.24 -r1.25
--- RequestUtil.pod 15 Jul 2004 20:51:08 -0000 1.24
+++ RequestUtil.pod 16 Jul 2004 01:11:03 -0000 1.25
@@ -64,6 +64,9 @@
# share perl objects like $r->notes
$r->pnotes($key => [$obj1, $obj2]);
+ # get HTML signature
+ $sig = $r->psignature($prefix);
+
# get the global request object (requires PerlOptions +GlobalRequest)
$r = Apache->request;
@@ -767,6 +770,38 @@
interface:
delete $r->pnotes->{foo};
+
+
+
+
+
+
+
+
+=head2 C<psignature>
+
+Get HTML describing the address and (optionally) admin of the server.
+
+ $sig = $r->psignature($prefix);
+
+=over 4
+
+=item obj: C<$r>
+( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
+
+=item arg1: C<$prefix> ( string )
+
+Text which is prepended to the return value
+
+=item ret: C<$sig> ( string )
+
+HTML text describing the server. Note that depending on the value of
+the C<ServerSignature> directive, the function may return the address,
+including the admin information or nothing at all.
+
+=item since: 1.99_15
+
+=back
1.25 +72 -45 modperl-docs/src/docs/2.0/api/Apache/ServerUtil.pod
Index: ServerUtil.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/ServerUtil.pod,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -u -r1.24 -r1.25
--- ServerUtil.pod 15 Jul 2004 20:51:08 -0000 1.24
+++ ServerUtil.pod 16 Jul 2004 01:11:03 -0000 1.25
@@ -12,8 +12,8 @@
$s = Apache->server;
my $srv_cfg = $s->dir_config;
- # get 'conf/' dir path using $s
- my $conf_dir = $s->server_root_relative('conf');
+ # get 'conf/' dir path using (avoid using this function!)
+ my $dir = Apache::ServerUtil::server_root_relative($r->pool, 'conf');
# server level PerlOptions flags lookup
$s->push_handlers(ChildExit => \&child_exit)
@@ -147,6 +147,9 @@
mod_perl/1.99_15-dev Perl/v5.8.5 Hikers, Inc/0.99999
configured -- resuming normal operations
+Also remember that the C<ServerTokens> directive value controls
+whether the component information is displayed or not.
+
@@ -456,36 +459,6 @@
-
-=head2 C<psignature>
-
-META: Autogenerated - needs to be reviewed/completed
-
-Get HTML describing the address and (optionally) admin of the server.
-
- $sig = $rXXXX->psignature($prefix);
-
-=over 4
-
-=item obj: C<$rXXX>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
-
-=item arg1: C<$prefix> ( string )
-
-Text which is prepended to the return value
-
-=item ret: C<$sig> ( string )
-
-HTML describing the server
-
-=item since: 1.99_10
-
-=back
-
-
-
-
-
-
=head2 C<push_handlers>
Add one or more handlers to a list of handlers to be called for a
@@ -563,6 +536,8 @@
+
+
=head2 C<server_root>
returns the value set by the top-level C<ServerRoot> directive.
@@ -584,25 +559,31 @@
-
-
-
=head2 C<server_root_relative>
Returns the canonical form of the filename made absolute to
C<ServerRoot>:
- $path = $s->server_root_relative($fname);
+ $path = Apache::ServerUtil::server_root_relative($pool, $fname);
=over 4
-=item obj: C<$s>
-( C<L<Apache::ServerRec object|docs::2.0::api::Apache::ServerRec>> )
+=item arg1: C<$pool>
+( C<L<APR::Pool object|docs::2.0::api::APR::Pool>> )
+
+Make sure that you read the following explanation and understand well
+which pool object you need to pass before using this function.
=item opt arg2: C<$fname> ( string )
=item ret: C<$path> ( string )
+The concatenation of C<ServerRoot> and the C<$fname>.
+
+If C<$fname> is not specified, the value of C<ServerRoot> is returned
+with a trailing C</>. (it's the same as using C<''> as C<$fname>'s
+value).
+
=item since: 1.99_10
=back
@@ -610,15 +591,61 @@
C<$fname> is appended to the value of C<ServerRoot> and returned. For
example:
- my $log_dir = Apache::server_root_relative($r->pool, 'logs');
+ my $dir = Apache::ServerUtil::server_root_relative($r->pool, 'logs');
+
+You must be extra-careful when using this function. If you aren't sure
+what you are doing don't use it.
+
+It's much safer to build the path by yourself using use
+C<L<Apache::ServerUtil::server_root()|/C_Apache__server_root_>>, For
+example:
+
+ use File::Spec::Functions qw(catfile);
+ my $path = catfile Apache::ServerUtil::server_root, qw(t logs);
+
+In this example, no memory allocation happens on the Apache-side and
+you aren't risking to get a memory leak.
+
+The problem with C<server_root_relative> is that Apache allocates
+memory to concatenate the path string. The memory is allocated from
+the pool object. If you call this method on the server pool object
+it'll allocate the memory from it. If you do that at the server
+startup, it's perfectly right, since you will do that only
+once. However if you do that from within a request or a connection
+handler, you create a memory leak every time it is called -- as the
+memory gets allocated from the server pool, it will be freed only when
+the server is shutdown. Therefore if you need to build a relative to
+the root server path for the duration of the request, use the request
+pool:
+
+ use Apache::RequestRec ();
+ Apache::ServerUtil::server_root_relative($r->pool, $fname);
+
+If you need to have the path for the duration of a connection
+(e.g. inside a protocol handler), you should use:
+
+ use Apache::Connection ();
+ Apache::ServerUtil::server_root_relative($c->pool, $fname);
+
+And if you want it for the scope of the server file:
+
+ use Apache::Process ();
+ use Apache::ServerUtil ();
+ Apache::ServerUtil::server_root_relative($s->process->pool, $fname);
+
+Moreover, you could have encountered the opposite problem, where you
+have used a short-lived pool object to construct the path, but tried
+to use the resulting path variable, when that pool has been destructed
+already. In order to avoid mysterious segmentation faults, mod_perl
+does a wasteful copy of the path string when returning it to you --
+another reason to avoid using this function.
+
+
+
+
+
-If C<$fname> is not specified, the value of C<ServerRoot> is returned
-with a trailing C</>. (it's the same as using C<''> as C<$fname>'s
-value).
-Also see the
-C<L<Apache::ServerUtil::server_root|/C_Apache__server_root_>>
-constant.
1.4 +9 -9 modperl-docs/src/docs/2.0/api/ModPerl/RegistryLoader.pod
Index: RegistryLoader.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/ModPerl/RegistryLoader.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -u -r1.3 -r1.4
--- RegistryLoader.pod 19 Jan 2004 20:04:32 -0000 1.3
+++ RegistryLoader.pod 16 Jul 2004 01:11:03 -0000 1.4
@@ -6,9 +6,9 @@
# in startup.pl
use ModPerl::RegistryLoader ();
- use APR::Pool ();
+ use File::Spec ();
- # explicit uri => filename mapping
+ # explicit uri => filename mapping
my $rlbb = ModPerl::RegistryLoader->new(
package => 'ModPerl::RegistryBB',
debug => 1, # default 0
@@ -19,9 +19,9 @@
###
# uri => filename mapping using a helper function
sub trans {
- my $uri = shift;
+ my $uri = shift;
$uri =~ s|^/registry/|cgi-bin/|;
- return Apache::Server::server_root_relative(APR::Pool->new, $uri);
+ return File::Spec->catfile(Apache::ServerUtil::server_root, $uri);
}
my $rl = ModPerl::RegistryLoader->new(
package => 'ModPerl::Registry',
@@ -129,18 +129,18 @@
{
# test the scripts pre-loading by using trans sub
use ModPerl::RegistryLoader ();
- use APR::Pool ();
+ use File::Spec ();
use DirHandle ();
use strict;
- my $pool = APR::Pool->new;
-
- my $dir = Apache::Server::server_root_relative($pool, "cgi-bin");
+ my $dir = File::Spec->catdir(Apache::ServerUtil::server_root,
+ "cgi-bin");
sub trans {
my $uri = shift;
$uri =~ s|^/registry/|cgi-bin/|;
- return Apache::Server::server_root_relative($pool, $uri);
+ return File::Spec->catfile(Apache::ServerUtil::server_root,
+ $uri);
}
my $rl = ModPerl::RegistryLoader->new(
1.42 +4 -2 modperl-docs/src/docs/2.0/user/handlers/http.pod
Index: http.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v
retrieving revision 1.41
retrieving revision 1.42
diff -u -u -r1.41 -r1.42
--- http.pod 15 Jul 2004 20:51:08 -0000 1.41
+++ http.pod 16 Jul 2004 01:11:03 -0000 1.42
@@ -168,7 +168,7 @@
my $r = shift;
$r->content_type('text/plain');
- my $conf_file = catfile $r->server_root_relative,
+ my $conf_file = catfile Apache::ServerUtil::server_root,
"conf", "httpd.conf";
printf "$conf_file is %0.2f minutes old\n", 60*24*(-M $conf_file);
@@ -1278,7 +1278,9 @@
use Apache::RequestRec ();
use Apache::Connection ();
+
use Fcntl qw(:flock);
+ use File::Spec::Functions qw(catfile);
use Apache::Const -compile => qw(OK DECLINED);
@@ -1292,7 +1294,7 @@
$r->connection->remote_ip, scalar(localtime),
$r->uri, $r->status, $r->bytes_sent;
- my $log_path = join '/', $r->server_root_relative,
+ my $log_path = catfile Apache::ServerUtil::server_root,
"logs", "$username.log";
open my $fh, ">>$log_path" or die "can't open $log_path: $!";
flock $fh, LOCK_EX;
1.18 +5 -8 modperl-docs/src/docs/2.0/user/handlers/server.pod
Index: server.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/server.pod,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -u -r1.17 -r1.18
--- server.pod 15 Jul 2004 20:51:08 -0000 1.17
+++ server.pod 16 Jul 2004 01:11:03 -0000 1.18
@@ -68,12 +68,12 @@
use Apache::Const -compile => 'OK';
- my $log_file = catfile "logs", "startup_log";
+ my $log_path = catfile Apache::ServerUtil::server_root,
+ "logs", "startup_log";
my $log_fh;
sub open_logs {
my($conf_pool, $log_pool, $temp_pool, $s) = @_;
- my $log_path = $s->server_root_relative($log_file);
$s->warn("opening the log file: $log_path");
open $log_fh, ">>$log_path" or die "can't open $log_path: $!";
@@ -232,7 +232,6 @@
sub open_logs {
my($conf_pool, $log_pool, $temp_pool, $s) = @_;
- my $log_path = $s->server_root_relative($log_file);
$s->warn("opening the log file: $log_path");
open $log_fh, ">>$log_path" or die "can't open $log_path: $!";
@@ -242,11 +241,9 @@
return Apache::OK;
}
-In our example the handler uses the function
-C<Apache::Server::server_root_relative()> to set the full path to the log
-file, which is then opened for appending and set to unbuffered
-mode. Finally it logs the fact that it's running in the parent
-process.
+In our example the handler opens a log file for appending and sets the
+filehandle to unbuffered mode. It then logs the fact that it's running
+in the parent process.
As you've seen in the example this handler is configured by adding to
the top level of I<httpd.conf>:
1.58 +3 -5 modperl-docs/src/docs/2.0/user/install/install.pod
Index: install.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/install/install.pod,v
retrieving revision 1.57
retrieving revision 1.58
diff -u -u -r1.57 -r1.58
--- install.pod 12 Jul 2004 23:13:22 -0000 1.57
+++ install.pod 16 Jul 2004 01:11:03 -0000 1.58
@@ -439,12 +439,10 @@
in I<httpd.conf> or:
- use Apache::ServerRec ();
use Apache::ServerUtil ();
- use Apache::Process ();
- my $pool = Apache->server->process->pool;
- push @INC, Apache::Server::server_root_relative($pool, "");
- push @INC, Apache::Server::server_root_relative($pool, "lib/perl");
+ use File::Spec::Functins qw(catfile);
+ push @INC, catfile Apache::ServerUtil::server_root, "";
+ push @INC, catfile Apache::ServerUtil::server_root, "lib/perl";
in I<startup.pl>.
1.3 +3 -3 modperl-docs/src/docs/2.0/user/performance/prevent.pod
Index: prevent.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/performance/prevent.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -u -r1.2 -r1.3
--- prevent.pod 19 Jan 2004 20:04:32 -0000 1.2
+++ prevent.pod 16 Jul 2004 01:11:03 -0000 1.3
@@ -31,11 +31,11 @@
can. Never use server pools during request, when you can use a request
pool. For example inside an HTTP handler, don't call:
- my $conf_dir = Apache::Server::server_root_relative($s->pool, 'conf');
+ my $dir = Apache::ServerUtil::server_root_relative($s->process->pool,
'conf');
-when you can call:
+when you should call:
- my $conf_dir = Apache::Server::server_root_relative($r->pool, 'conf');
+ my $dir = Apache::ServerUtil::server_root_relative($r->pool, 'conf');
Of course on special occasions, you may want to have something
allocated off the server pool if you want the allocated memory to
1.58 +12 -14 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.57
retrieving revision 1.58
diff -u -u -r1.57 -r1.58
--- compat.pod 15 Jul 2004 20:51:09 -0000 1.57
+++ compat.pod 16 Jul 2004 01:11:03 -0000 1.58
@@ -1054,33 +1054,31 @@
C<L<Apache::compat|docs::2.0::api::Apache::compat>>. 2.0 handlers only
need to set the I<Content-type> via C<$r-E<gt>content_type($type)>.
-=head2 C<$r-E<gt>server_root_relative>
-C<Apache::server_root_relative> is a function in 2.0 and its first
-argument is the I<pool> object. For example:
- # during request
- my $conf_dir = Apache::server_root_relative($r->pool, 'conf');
- # during startup
- my $conf_dir = Apache::server_root_relative($s->pool, 'conf');
-Alternatively:
+
+=head2 C<$r-E<gt>server_root_relative>
+
+This method was replaced with
+C<L<Apache::ServerUtil::server_root_relative|docs::2.0::Apache::ServerUtil/C_server_root_relative_>>
+function and its first argument is a I<pool> object. For example:
# during request
- my $conf_dir = $r->server_root_relative('conf');
+ $conf_dir = Apache::server_root_relative($r->pool, 'conf');
# during startup
- my $conf_dir = $c->server_root_relative('conf');
+ $conf_dir = Apache::server_root_relative($s->pool, 'conf');
Note that the old form
my $conf_dir = Apache->server_root_relative('conf');
-is no longer valid - C<Apache::server_root_relative> must be called
-from either one of C<$r>, C<$s>, or C<$c>, or be explicitly
-passed a pool.
+is no longer valid - C<Apache::server_root_relative> must be
+explicitly passed a pool.
+The old functionality is available with
+C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
-See the L<Apache::ServerUtil> manpage.
=head2 C<$r-E<gt>hard_timeout>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
