The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

Apache2::SizeLimit - Because size does matter.

SYNOPSIS

PerlLoadModule Apache2::SizeLimit

<Perl>
 Apache2::SizeLimit->set_max_process_size(150_000);   # Max size in KB
 Apache2::SizeLimit->set_min_shared_size(10_000);     # Min share in KB
 Apache2::SizeLimit->set_max_unshared_size(120_000);  # Max unshared size in KB
</Perl>

PerlCleanupHandler Apache2::SizeLimit

DESCRIPTION

******************************** NOTICE *******************

This version is only for httpd 2.x and mod_perl 2.x
series.

For httpd 1.3.x / mod_perl 1.x Apache::SizeLimit 
documentation please read the perldoc in 
lib/Apache/SizeLimit.pm

******************************** NOTICE *******************

This module allows you to kill off Apache httpd processes if they grow too large. You can make the decision to kill a process based on its overall size, by setting a minimum limit on shared memory, or a maximum on unshared memory.

You can set limits for each of these sizes, and if any limit is exceeded, the process will be killed.

You can also limit the frequency that these sizes are checked so that this module only checks every N requests.

This module is highly platform dependent, please read the "PER-PLATFORM BEHAVIOR" section for details. It is possible that this module simply does not support your platform.

API

You can set set the size limits from a Perl module or script loaded by Apache by calling the appropriate class method on Apache2::SizeLimit:

  • Apache2::SizeLimit->set_max_process_size($size)

    This sets the maximum size of the process, including both shared and unshared memory.

  • Apache2::SizeLimit->set_max_unshared_size($size)

    This sets the maximum amount of unshared memory the process can use.

  • Apache2::SizeLimit->set_min_shared_size($size)

    This sets the minimum amount of shared memory the process must have.

The two methods related to shared memory size are effectively a no-op if the module cannot determine the shared memory size for your platform. See "PER-PLATFORM BEHAVIOR" for more details.

Running the handler()

There are several ways to make this module actually run the code to kill a process.

The simplest is to make Apache2::SizeLimit a PerlCleanupHandler in your Apache config:

PerlCleanupHandler Apache2::SizeLimit

This will ensure that Apache2::SizeLimit->handler() is run for all requests.

If you want to combine this module with a cleanup handler of your own, make sure that Apache2::SizeLimit is the last handler run:

PerlCleanupHandler  Apache2::SizeLimit My::CleanupHandler

Remember, mod_perl will run stacked handlers from right to left, as they're defined in your configuration.

If you have some cleanup code you need to run, but stacked handlers aren't appropriate for your setup, you can also explicitly call the Apache2::SizeLimit->handler() function from your own cleanup handler:

package My::CleanupHandler

sub handler {
    my $r = shift;

    # Causes File::Temp to remove any temp dirs created during the
    # request
    File::Temp::cleanup();

    return Apache2::SizeLimit->handler($r);
}
  • Apache2::SizeLimit->add_cleanup_handler($r)

    You can call this method inside a request to run Apache2::SizeLimit's handler() method for just that request. It's safe to call this method repeatedly -- the cleanup will only be run once per request.

Checking Every N Requests

Since checking the process size can take a few system calls on some platforms (e.g. linux), you may not want to check the process size for every request.

  • Apache2::SizeLimit->set_check_interval($interval)

    Calling this causes Apache2::SizeLimit to only check the process size every $interval requests. If you want this to affect all processes, make sure to call this during server startup.

SHARED MEMORY OPTIONS

In addition to simply checking the total size of a process, this module can factor in how much of the memory used by the process is actually being shared by copy-on-write. If you don't understand how memory is shared in this way, take a look at the mod_perl docs at http://perl.apache.org/docs/.

You can take advantage of the shared memory information by setting a minimum shared size and/or a maximum unshared size. Experience on one heavily trafficked mod_perl site showed that setting maximum unshared size and leaving the others unset is the most effective policy. This is because it only kills off processes that are truly using too much physical RAM, allowing most processes to live longer and reducing the process churn rate.

PER-PLATFORM BEHAVIOR

This module is highly platform dependent, since finding the size of a process is different for each OS, and some platforms may not be supported. In particular, the limits on minimum shared memory and maximum shared memory are currently only supported on Linux and BSD. If you can contribute support for another OS, patches are very welcome.

Currently supported OSes:

linux

For linux we read the process size out of /proc/self/statm. If you are worried about performance, you can consider using Apache2::SizeLimit->set_check_interval() to reduce how often this read happens.

solaris 2.6 and above

For solaris we simply retrieve the size of /proc/self/as, which contains the address-space image of the process, and convert to KB. Shared memory calculations are not supported.

NOTE: This is only known to work for solaris 2.6 and above. Evidently the /proc filesystem has changed between 2.5.1 and 2.6. Can anyone confirm or deny?

BSD (and OSX)

Uses BSD::Resource::getrusage() to determine process size. This is pretty efficient (a lot more efficient than reading it from the /proc fs anyway).

According to recent tests on OSX (July, 2006), BSD::Resource simply reports zero for process and shared size on that platform, so OSX is not supported by Apache2::SizeLimit.

AIX?

Uses BSD::Resource::getrusage() to determine process size. Not sure if the shared memory calculations will work or not. AIX users?

Win32

Uses Win32::API to access process memory information. Win32::API can be installed under ActiveState perl using the supplied ppm utility.

Everything Else

If your platform is not supported, then please send a patch to check the process size. The more portable/efficient/correct the solution the better, of course.

ABOUT THIS MODULE

This module was written in response to questions on the mod_perl mailing list on how to tell the httpd process to exit if it gets too big.

Actually, there are two big reasons your httpd children will grow. First, your code could have a bug that causes the process to increase in size very quickly. Second, you could just be doing operations that require a lot of memory for each request. Since Perl does not give memory back to the system after using it, the process size can grow quite large.

This module will not really help you with the first problem. For that you should probably look into Apache::Resource or some other means of setting a limit on the data size of your program. BSD-ish systems have setrlimit(), which will kill your memory gobbling processes. However, it is a little violent, terminating your process in mid-request.

This module attempts to solve the second situation, where your process slowly grows over time. It checks memory usage after every request, and if it exceeds a threshold, exits gracefully.

By using this module, you should be able to discontinue using the Apache configuration directive MaxRequestsPerChild, although for some folks, using both in combination does the job.

DEPRECATED APIS

Previous versions of this module documented three globals for defining memory size limits:

  • $Apache2::SizeLimit::MAX_PROCESS_SIZE

  • $Apache2::SizeLimit::MIN_SHARE_SIZE

  • $Apache2::SizeLimit::MAX_UNSHARED_SIZE

  • $Apache2::SizeLimit::CHECK_EVERY_N_REQUESTS

Direct use of these globals is deprecated, but will continue to work for the foreseeable future.

It also documented three functions for use from registry scripts:

  • Apache2::SizeLimit::setmax()

  • Apache2::SizeLimit::setmin()

  • Apache2::SizeLimit::setmax_unshared()

Besides setting the appropriate limit, these functions also add a cleanup handler to the current request. In the 2.x series of mod_perl to use the deprecated functions, you must set PerlOptions +GlobalRequest accordingly.

SUPPORT

The Apache-SizeLimit project is co-maintained by several developers, who take turns at making CPAN releases. Therefore you may find several CPAN directories containing Apache-SizeLimit releases. The best way to find the latest release is to use http://search.cpan.org/.

If you have a question or you want to submit a bug report or make a contribution, please do not email individual authors, but send an email to the modperl <at> perl.apache.org mailing list. This list is moderated, so unless you are subscribed to it, your message will have to be approved first by a moderator. Therefore please allow some time (up to a few days) for your post to propagate to the list.

AUTHOR

Doug Bagley <doug+modperl@bagley.org>, channeling Procrustes.

Brian Moseley <ix@maz.org>: Solaris 2.6 support

Doug Steinwand and Perrin Harkins <perrin@elem.com>: added support for shared memory and additional diagnostic info

Matt Phillips <mphillips@virage.com> and Mohamed Hendawi <mhendawi@virage.com>: Win32 support

Dave Rolsky <autarch@urth.org>, maintenance and fixes outside of mod_perl tree (0.9+).