/ 
Process-MaxSize-0.04
River stage zero No dependents
/ Process::MaxSize

NAME

Process::MaxSize - Restart processes when they exceed a size limit

SYNOPSIS

    use Process::MaxSize;

      # Limit the process to 100 MB
    my $watchdog = Process::MaxSize->new(
                       max_size => "100m"
    );

    while(1) {
        ... your code here ...

	  # restarts the process if memory limit is exceeded
        $watchdog->check();
    }

DESCRIPTION

Process::MaxSize helps to contain perl programs that leak memory. It defines a watchdog that, at well defined locations within a program, checks the current process size and triggers a restart routine in case a predefined size limit is exceeded.

To define a new watchdog, use the Process::MaxSize constructor:

my $watchdog = Process::MaxSize->new();

By default, the memory watchdog will be set to 10M of memory and a restart function that execs the same process again with a copy of all command line arguments. To use different settings, let the constructor know:

my @argv = @ARGV;

  # Limit the process to 100 MB
my $watchdog = Process::MaxSize->new(
    max_size => "100m",
    restart  => sub { exec($0, @argv) or 
                        die "Can't restart!" },
);

max_size specifies the maximum real memory consumption allowed in KBytes, unless the letter "m" indicates that you mean MBytes.

restart is a code ref that performs an arbitrary action. By default, the current program gets restarted via exec and a copy of its command line arguments @ARGV. Process::MaxSize is going to change to the original start directory (of the time the constructor was called) before calling the restart routine.

The check method checks the current memory consumption and triggers the restart routine if the limit is exceeded:

$watchdog->check();

You want to plant the call to the check() method at a location

  • where the program whizzes by periodically to make sure you check as soon as the process exceeds the memory limit and

  • where the program can be safely terminated and restarted.

By default, Process::MaxSize will sleep 2 seconds before restarting the process. This is to prevent that it will hog the CPU if something goes wrong with the exec and the process ends up in an infinite loop. To eliminate this precautious setting, set the sleep parameter to the required number of seconds in the constructor call:

my $watchdog = Process::MaxSize->new(
    sleep    => 0,
);

The restart method doesn't need to restart the program. It can be used to simply set a flag which indicates another part of the program that the preset size limit has been exceeded:

my $watchdog = Process::MaxSize->new(
    restart  => sub { $out_of_memory = 1 },
);

This can come in handy when the program flow requires that the program needs to terminate/restart at a different point in the flow than the location where it detects that the process exceeds the memory limits.

Which process size?

To measure the process size, Process::MaxSize defines a method process_size() which returns the current real memory (resident set) size of the process in 1024 byte units. If you like to measure the virtual memory size instead or want to employ a different method than the somewhat crude call to "ps" (Proc::ProcessTable comes to mind), just create a subclass of Process::MaxSize and override the process_size() method to return the number of used KBytes.

Debugging/Logging

Process::MaxSize is Log::Log4perl-enabled and will start logging as soon as Log::Log4perl gets initialized:

use Log::Log4perl qw(:easy);
Log::Log4perl->easy_init($DEBUG);

As usual with Log::Log4perl, this is completely optional.

LEGALESE

Copyright 2007 by Mike Schilli, all rights reserved. This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

2007, Mike Schilli <m@perlmeister.com>