NAME
    Proc::NiceSleep - yield system in an intelligent fashion

SYNOPSIS
      use Proc::NiceSleep qw( :all ); 
      nice(5);              # lower our priority, if our OS supports it 
      max_load(1.1);        # max load we allow, if GetCpuLoad can find loads
      sleep_factor(.5);     # sleep 50% as long as we run
      min_run_time(2);      # run at least 2 seconds without sleep
      while($somecondition) {
        #dosomething();
        $slept = maybe_sleep(); # sleep some amount of time if needed 
      }

DESCRIPTION
    Proc::NiceSleep defines subroutines to allow a process to yield use of
    the system according to a configured policy. Proc::NiceSleep is intended
    for use in situations where the operating system does not support
    priorities, or where using the operating system's built-in priorities
    does not yield the system sufficiently.

    By default Proc::NiceSleep expects to yield the process for one tenth
    the amount of time that process runs. This is expressed by the default
    Sleep Factor of 0.10. Proc::NiceSleep can also be configured to attempt
    to keep the average system load below a certain threshhold through use
    of the max_load() function.

    A convenient nice() function, which acts much like the shell command and
    executable of the same name, is also provided for easy, platform
    independent access to your system's priorities (if available).

    If Proc::NiceSleep autodetects the presence of the Time::HiRes module
    (and your operating system supports it) then timing and yielding
    operations will occur with sub-second granularity. If not, no warning or
    error will be issued but Proc::NiceSleep operations will occur with a
    granularity of about one second. Sys::CpuLoad must be found for
    max_load() to have any effect.

    The following functions can be imported from this module.

    maybe_sleep ()
        Checks to see if this process should yield use of the system by
        issuing some kind of sleep at this point, and if so, does so for an
        appropriate amount of time. Returns 0 if no sleep was performed,
        otherwise returns the amount of seconds maybe_sleep() actually slept
        for.

    max_load ()
        Set or gets the maximum 1-minute average load allowed to occur
        before a sleep call will be issued by maybe_sleep(). The default
        value of 0 disables this feature; setting the maximum load will only
        have an effect if Sys::CpuLoad is successfully loaded (or an
        alternate load retrieval function is provided through
        load_function()). This module will check the system load no more
        than about once per second. If both sleep_factor() and max_load()
        are used then maybe_sleep() will yield the system if either
        condition is met.

    sleep_factor ()
        Sets or gets the sleep factor depending on whether a number is
        passed or not. A sleep factor of 1 means to sleep an equal amount of
        time as we run, 2 means to sleep twice as long, and so on. The
        default value is 0.1. If the sleep factor is set to zero, then this
        feature is disabled. If both sleep_factor() and max_load() are used
        then maybe_sleep() will yield the system if either condition is met.

    nice ()
        Sets or gets the priority of the process, as understood by the
        operating system. If passed an integer, nice() attempts to set
        priority of the process to the value specified, and returns that
        value. If no parameter is passed, nice() attempts to query the
        operating system for the priority of the process and return it. If
        your OS doesn't support priorities then nice() will likely have no
        effect and always return 0.

        The exact nice() values returned and recognized, and their meanings
        to the system, are system dependent but usually range from about -20
        (highest priority) to 20 (lowest priority, 'nicest').

    min_run_time ()
        Sets or gets the minimum run time, in seconds, depending on whether
        a number is passed or not. The minumum run time is the least amount
        of time that Proc::NiceSleep will allow the process to run between
        sleeps. The default value is 0 seconds.

    min_sleep_time ()
        Sets or gets the minimum amount time, in seconds, that maybe_sleep()
        will sleep for if it detects that a sleep is appropriate. The
        default it 0.

    over_load_min_sleep_time ()
        Sets or gets the minimum amount time, in seconds, that maybe_sleep()
        will sleep when the load has gone above the max_load(). The default
        is 3.5 seconds.

    over_load_sleep_drift ()
        Sets or gets the 'drift' in the amount time, that maybe_sleep() will
        sleep when the load has gone above the value set with max_load().
        The actual amount of time chosen to sleep will be between
        over_load_min_sleep_time() and over_load_min_sleep_time() + ( 4 *
        (curload - targetload) * over_load_sleep_drift() ) seconds (that is,
        it will sleep longer as the system load goes up.) The default is
        over_load_sleep_drift is 1.

    load_function( \&function )
        Sets or gets a reference to a function to be used by maybe_sleep()
        that returns numbers that should be considered the 1, 5, and
        15-minute average system loads. (Only the 1-minute average is used).
        Set to undef (the default) to use your system's load.

    DumpText ()
        Returns a string (intended for display) containing multiple lines
        with internal information about Proc::NiceSleep's runtime
        configuration and statistics. The format and contents of the
        returned string are intended for informational and debugging use and
        are subject to change.

    Dump ()
        Returns a reference to a hash with internal information about
        Proc::NiceSleep configuration and statistics. The names and presence
        of the returned hash names and values are for informational and
        debugging purposes only and are subject to change. Modifying the
        returned hash will have no effect on the operation of
        Proc::NiceSleep.

EXPORT
    None by default.

AUTHOR
    Josh Rabinowitz, <joshr-proc-nicesleep@joshr.com>

CAVEATS
    The meanings of values accepted by nice() may vary between operating
    systems (e.g. HP-UX). This problem is to be addressed in future
    revisions to this package; for now be advised that use of nice() is not
    necessarily portable.

    Uncoordinated use of sleep() (and possibly of signal() and alarm()) in
    your perl program may cause your program to yield the system more or
    less than specified via Proc::NiceSleep policies.

SEE ALSO
    Time::HiRes, Sys::CpuLoad

COPYRIGHT
    Copyright (c) 2002-2010 Josh Rabinowitz. All rights reserved. This program is
    free software; you can redistribute it and/or modify it under the same
    terms as Perl itself.

ACKNOWLEDGEMENTS
    Proc::NiceSleep is loosely modeled on Lincoln Stein's CGI.pm, and on D.
    Wegscheid and other's Time::HiRes.pm. Thanks to Michael G Schwern,
    Terrence Brannon, and David Alban for their valuable input.

LINKS
            http://search.cpan.org/~joshr/  : CPAN home page
            http://joshr.com/src/           : my website

  MAILING LISTS
    There is a mailing list for discussion of all aspects of Proc::NiceSleep
    use at http://mail.joshr.com/mailman/listinfo/proc-nicesleep/

    and a list for discussions of a more development-related nature at
    http://mail.joshr.com/mailman/listinfo/proc-nicesleep-dev/

    there is also a very occasionally used list with announcements about
    Proc::NiceSleep, information about it can be found at
    http://mail.joshr.com/mailman/listinfo/proc-nicesleep-announce/

  REFERENCE LINKS
    Here's the reference to the original posting to the perl modules list
    requesting the namespace Proc::NiceSleep, and offering a rationale for
    its acceptance and use:

      http://www.xray.mpe.mpg.de/mailing-lists/modules/2002-02/msg00329.html

    The Proc::NiceSleep info page on search.cpan.org is a good place to
    start: http://search.cpan.org/~joshr/Proc-NiceSleep/

    This module's 'perl-testers' status, on testers.cpan.org (Proc-NiceSleep
    was first covered by perl-testers Feb 21 2002):

      http://testers.cpan.org/show/Proc-NiceSleep.html

GETTING HELP
    If you have questions about Proc::NiceSleep, you can get help from the
    proc-nicesleep-at-joshr.com mailing list (replace -at- with @). You can
    subscribe to the list by sending the word 'subscribe' (no quotes) in the
    body of an email to

             proc-nicesleep-request-at-joshr.com

    There is also a Proc::NiceSleep announcement mailing list, to subscribe
    send an email with just the word 'subscribe' in the email to

             proc-nicesleep-announce-request-at-joshr.com 

