Re: Just Uploaded: ModPerl2::Tools

2010/3/2 Torsten Förtsch <[email protected]>:
> Not much, just a few problems solved. Comments are welcome.

Looks very cool!  I know there are a couple of hooks in APR that
aren't mapped into mod_perl space yet, such as apr_proc_create().
Have you thought about adding those to mod_perl core for a more native
and portable forking solution?

>
> NAME
>    ModPerl2::Tools - a few hopefully useful tools
>
> SYNOPSIS
>     use ModPerl2::Tools;
>
>     ModPerl2::Tools::spawn +{keep_fd=>[3,4,7], survive=>1}, sub {...};
>     ModPerl2::Tools::spawn +{keep_fd=>[3,4,7], survive=>1}, qw/bash -c .../;
>
>     ModPerl2::Tools::safe_die $status;
>     $r->safe_die($status);
>     $f->safe_die($status);
>
>     $content=ModPerl2::Tools::fetch_url $url;
>     $content=$r->fetch_url($url);
>
> INSTALLATION
>     perl Makefile.PL
>     make
>     make test
>     make install
>
> DESCRIPTION
>    This module is a collection of functions and methods that I found useful
>    when working with "mod_perl". I work mostly under Linux. So, I don't
>    expect all of these functions to work on other operating systems.
>
>  Forking off long running processes
>    Sometimes one needs to spawn off a long running process as the result of
>    a request. Under modperl this is not as simple as calling "fork" because
>    that way all open file descriptors would be inherited by the child and,
>    more subtle, the long running process would be killed when the
>    administrator shuts down the web server. The former is usually
>    considered a security issue, the latter a design decision.
>
>    There is already $r->spawn_proc_prog that serves a similar purpose as
>    the "spawn" function. However, "spawn_proc_prog" is not usable for long
>    running processes because it kills the children after a certain timeout.
>
>   Solution
>     $pid=ModPerl2::Tools::spawn \%options, $subroutine, @parameters;
>
>    or
>
>     $pid=ModPerl2::Tools::spawn \%options, @command_line;
>
>    "spawn" expects as the first parameter an options hash reference. The
>    second parameter may be a code reference or a string.
>
>    In case of a code ref no other program is executed but the subroutine is
>    called instead. The remaining parameters are passed to this function.
>
>    Note, the perl environment under modperl differs in certain ways from a
>    normal perl environment. For example %ENV is not bound to the C-level
>    "environ". These modifications are not undone by this module. So, it's
>    generally better to execute another perl interpreter instead of using
>    the $subroutine feature.
>
>    The options parameter accepts these options:
>
>    keep_fd => \@fds
>        here an array of file descriptor numbers (not file handles) is
>        expected. All other file descriptors except for the listed and file
>        descriptor 2 (STDERR) are closed before calling $subroutine or
>        executing @command_line.
>
>    survive => $boolean
>        if passed "false" the created process will be killed when Apache
>        shuts down. if true it will survive an Apache restart.
>
>    The return code on success is the PID of the process. On failure "undef"
>    or an empty string is returned.
>
>    The created process is not related as a child process to the current
>    apache child.
>
>  Serving "ErrorDocument"s
>    Triggering "ErrorDocument"s from a registry script or even more from an
>    output filter is not simple. The normal way as a handler is
>
>      return Apache2::Const::STATUS;
>
>    This does not work for registry scripts. An output filter even if it
>    returns a status can trigger only a "SERVER_ERROR".
>
>    The main interface to enter standard error processing in Apache is
>    "ap_die()" at C-level. Its Perl interface is hidden in Apache2::HookRun.
>
>    There is one case when an error message cannot be sent to the user. This
>    happens if the HTTP headers are already on the wire. Then it is too
>    late.
>
>    The various flavors of "safe_die()" take this into account.
>
>    ModPerl2::Tools::safe_die $status
>        This function is designed to be called from registry scripts. It
>        uses Apache2::RequestUtil->request to fetch the current request
>        object. So,
>
>         PerlOption +GlobalRequest
>
>        must be enabled.
>
>        Usage example:
>
>         ModPerl2::Tools::safe_die 401;
>         exit 0;
>
>    $r->safe_die($status)
>    $f->safe_die($status)
>        These 2 methods are to be used if a request object or a filter
>        object are available.
>
>        Usage from within a filter:
>
>         package My::Filter;
>         use strict;
>         use warnings;
>
>         use ModPerl2::Tools;
>         use base 'Apache2::Filter';
>
>         sub handler : FilterRequestHandler {
>           my ($f, $bb)=@_;
>           return $f->safe_die(410);
>         }
>
>        The filter flavor removes the current filter from the request's
>        output filter chain.
>
>  Fetching the content of another document
>    Sometimes a handler or a filter needs the content of another document in
>    the web server's realm. Apache provides subrequests for this purpose.
>
>    The 2 "fetch_url" variants use a subrequest to fetch the content of
>    another document. The document can even be fetched via "mod_proxy" from
>    another server. However, fetching a document directly as with LWP for
>    example is not (yet) possible.
>
>    "ModPerl2::Tools::fetch_url" needs
>
>     PerlOption +GlobalRequest
>
>    Usage:
>
>     $content=ModPerl2::Tools::fetch_url '/some/where?else=42';
>
>     $content=$r->fetch_url('/some/where?else=42');
>
> EXPORTS
>    None.
>
> SEE ALSO
>    <http://perl.apache.org>
>
> AUTHOR
>    Torsten Förtsch, <[email protected]>
>
> COPYRIGHT AND LICENSE
>    Copyright (C) 2010 by Torsten Förtsch
>
>    This library is free software; you can redistribute it and/or modify it
>    under the same terms as Perl itself.
>
>
> Torsten Förtsch
>
> --
> Need professional modperl support? Hire me! (http://foertsch.name)
>
> Like fantasy? http://kabatinte.net
>