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 Fri, 16 Jul 2004 01:11:03 GMT
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: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message