######################################################################
    Process::MaxSize 0.01
######################################################################

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 "exec"s 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>