📄 serverutil.pm
字号:
=item since: 2.0.00=backFor example to check whether the C<ChildExit> hook is enabled (whichcan be disabled with C<PerlOptions -ChildExit>) and configure somehandlers to run if enabled: $s->push_handlers(ChildExit => \&child_exit) if $s->is_perl_option_enabled('ChildExit');See also:L<PerlOptions|docs::2.0::user::config::config/C_PerlOptions_> andL<the equivalent function for directory level PerlOptionsflags|docs::2.0::api::Apache2::RequestUtil/C_is_perl_option_enabled_>.=head2 C<method_register>Register a new request method, and return the offset that will beassociated with that method. $offset = $s->method_register($methname);=over 4=item obj: C<$s>( C<L<Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec>> )=item arg1: C<$methname> ( string )The name of the new method to register (in addition to the alreadysupported C<GET>, C<HEAD>, etc.)=item ret: C<$offset> ( integer )An int value representing an offset into a bitmask. You can probablyignore it.=item since: 2.0.00=backThis method allows you to extend the HTTP protocol to support newmethods, which fit the HTTP paradigm. Of course you will need towrite a client that understands that protocol extension. For a goodexample, refer to the C<MyApache2::SendEmail> example presented inC<L<the PerlHeaderParserHandlersection|docs::2.0::user::handlers::http/PerlHeaderParserHandler>>,which demonstrates how a new method C<EMAIL> is registered and used.=head2 C<push_handlers>Add one or more handlers to a list of handlers to be called for agiven phase. $ok = $s->push_handlers($hook_name => \&handler); $ok = $s->push_handlers($hook_name => [\&handler, \&handler2]);=over 4=item obj: C<$s>( C<L<Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec>> )=item arg1: C<$hook_name> ( string )the phase to add the handlers to=item arg2: C<$handlers> ( CODE ref or SUB name or an ARRAY ref )a single handler CODE reference or just a name of the subroutine(fully qualified unless defined in the current package).if more than one passed, use a reference to an array of CODE refsand/or subroutine names.=item ret: C<$ok> ( boolean )returns a true value on success, otherwise a false value=item since: 2.0.00=backSee also:C<L<$r-E<gt>add_config|docs::2.0::api::Apache2::RequestUtil/C_push_handlers_>>Examples:A single handler: $s->push_handlers(PerlChildExitHandler => \&handler);Multiple handlers: $s->push_handlers(PerlChildExitHandler => ['Foo::Bar::handler', \&handler2]);Anonymous functions: $s->push_handlers(PerlLogHandler => sub { return Apache2::Const::OK });=head2 C<restart_count>How many times the server was restarted. $restart_count = Apache2::ServerUtil::restart_count();=over 4=item ret: C<restart_count> ( number )=item since: 2.0.00=backThe following demonstration should make it clear what values to expectfrom this function. Let's add the following code to F<startup.pl>, soit's run every time F<httpd.conf> is parsed: use Apache2::ServerUtil (); my $cnt = Apache2::ServerUtil::restart_count(); open my $fh, ">>/tmp/out" or die "$!"; print $fh "cnt: $cnt\n"; close $fh;Now let's run a series of server starts and restarts and look at whatis logged into F</tmp/out>: % httpd -k start cnt: 1 cnt: 2 % httpd -k graceful cnt: 1 cnt: 3 % httpd -k graceful cnt: 1 cnt: 4 % httpd -k stop cnt: 1Remembering that L<Apache restarts itself immediately afterstarting|docs::2.0::user::handlers::server/Server_Life_Cycle>, we cansee that the C<restart_count> goes from 1 to 2 during the serverstart. Moreover we can see that every operation forces the parsing ofF<httpd.conf> and therefore reinitialization of mod_perl (and runningall the code found in F<httpd.conf>). This happens even when theserver is shutdown via C<httpd -k stop>.What conclusions can be drawn from this demonstration:=over=item *C<Apache2::ServerUtil::restart_count()> returns 1 every time some C<-k>command is passed to Apache (or C<kill -USR1> or some alternativesignal is received).=item *At all other times the count will be 2 or higher. So for example ongraceful restart the count will be 3 or higher.=backFor example if you want to run something every time C<httpd -k> is runyou just need to check whether C<restart_count()> returns 1: my $cnt = Apache2::ServerUtil::restart_count(); do_something() if $cnt == 1;To do something only when server restarts (C<httpd -k start> orC<httpd -k graceful)>, check whether C<restart_count()> is bigger than1: my $cnt = Apache2::ServerUtil::restart_count(); do_something() if $cnt > 1;=head2 C<server>Get the main server's object $main_s = Apache2::ServerUtil->server();=over 4=item obj: C<Apache2> (class name)=item ret: C<$main_s>( C<L<Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec>> )=item since: 2.0.00=back=head2 C<server_root>returns the value set by the top-level C<ServerRoot> directive. $server_root = Apache2::ServerUtil::server_root();=over 4=item ret: C<$server_root> ( string )=item since: 2.0.00=back=head2 C<server_root_relative>Returns the canonical form of the filename made absolute toC<ServerRoot>: $path = Apache2::ServerUtil::server_root_relative($pool, $fname);=over 4=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 wellwhich 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 returnedwith a trailing C</>. (it's the same as using C<''> as C<$fname>'svalue).=item since: 2.0.00=backC<$fname> is appended to the value of C<ServerRoot> and returned. Forexample: my $dir = Apache2::ServerUtil::server_root_relative($r->pool, 'logs');You must be extra-careful when using this function. If you aren't surewhat you are doing don't use it.It's much safer to build the path by yourself using useC<L<Apache2::ServerUtil::server_root()|/C_Apache2__server_root_>>, Forexample: use File::Spec::Functions qw(catfile); my $path = catfile Apache2::ServerUtil::server_root, qw(t logs);In this example, no memory allocation happens on the Apache-side andyou aren't risking to get a memory leak.The problem with C<server_root_relative> is that Apache allocatesmemory to concatenate the path string. The memory is allocated fromthe pool object. If you call this method on the server pool objectit'll allocate the memory from it. If you do that at the serverstartup, it's perfectly right, since you will do that onlyonce. However if you do that from within a request or a connectionhandler, you create a memory leak every time it is called -- as thememory gets allocated from the server pool, it will be freed only whenthe server is shutdown. Therefore if you need to build a relative tothe root server path for the duration of the request, use the requestpool: use Apache2::RequestRec (); Apache2::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 Apache2::Connection (); Apache2::ServerUtil::server_root_relative($c->pool, $fname);And if you want it for the scope of the server file: use Apache2::Process (); use Apache2::ServerUtil (); Apache2::ServerUtil::server_root_relative($s->process->pool, $fname);Moreover, you could have encountered the opposite problem, where youhave used a short-lived pool object to construct the path, but triedto use the resulting path variable, when that pool has been destructedalready. In order to avoid mysterious segmentation faults, mod_perldoes a wasteful copy of the path string when returning it to you --another reason to avoid using this function.=head2 C<set_handlers>Set a list of handlers to be called for a given phase. Any previouslyset handlers are forgotten. $ok = $s->set_handlers($hook_name => \&handler); $ok = $s->set_handlers($hook_name => [\&handler, \&handler2]); $ok = $s->set_handlers($hook_name => []); $ok = $s->set_handlers($hook_name => undef);=over 4=item obj: C<$s>( C<L<Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec>> )=item arg1: C<$hook_name> ( string )the phase to set the handlers in=item arg2: C<$handlers> ( CODE ref or SUB name or an ARRAY ref )a reference to a single handler CODE reference or just a name of thesubroutine (fully qualified unless defined in the current package).if more than one passed, use a reference to an array of CODE refsand/or subroutine names.if the argument is C<undef> or C<[]> the list of handlers is reset tozero.=item ret: C<$ok> ( boolean )returns a true value on success, otherwise a false value=item since: 2.0.00=backSee also:C<L<$r-E<gt>add_config|docs::2.0::api::Apache2::RequestUtil/C_set_handlers_>>Examples:A single handler: $r->set_handlers(PerlChildExitHandler => \&handler);Multiple handlers: $r->set_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);Anonymous functions: $r->set_handlers(PerlLogHandler => sub { return Apache2::Const::OK });Reset any previously set handlers: $r->set_handlers(PerlCleanupHandler => []);or $r->set_handlers(PerlCleanupHandler => undef);=head1 Unsupported APIC<Apache2::ServerUtil> also provides auto-generated Perl interface fora few other methods which aren't tested at the moment and thereforetheir API is a subject to change. These methods will be finalizedlater as a need arises. If you want to rely on any of the followingmethods please contact the L<the mod_perl development mailinglist|maillist::dev> so we can help each other take the steps necessaryto shift the method to an officially supported API.=head2 C<error_log2stderr>Start sending STDERR to the error_log file $s->error_log2stderr();=over 4=item obj: C<$s>( C<L<Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec>> )The current server=item ret: no return value=item since: 2.0.00=backThis method may prove useful if you want to start redirecting STDERRto the error_log file before Apache does that on the startup.=head1 See AlsoL<mod_perl 2.0 documentation|docs::2.0::index>.=head1 Copyrightmod_perl 2.0 and its core modules are copyrighted underThe Apache Software License, Version 2.0.=head1 AuthorsL<The mod_perl development team and numerouscontributors|about::contributors::people>.=cut⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -