Proc/NiceSleep version 0.50

STATUS
   This is BETA software; it seems to work, but use it at you own risk.
   The API is subject to change until release 0.75, at which point it
   will be considered stable. 

   This module has been tested on linux, freebsd, and win32, but it 
   should work on any machine that runs perl. Comments, ideas, bug 
   reports, patches, and ports are greatly appreciated.

ABSTRACT
   Proc::NiceSleep is a Perl module which defines simple functions
   to allow a process to yield use of the system in a quasi-intelligent
   manner. See SYNOPSIS and DESCRIPTION below for details.

   The Proc::NiceSleep module is available on the Comprehensive Perl Archive 
   Network (CPAN). The latest version should always be available at 
   http://joshr.com/src/ ; http://cpan.perl.org/authors/id/J/JO/JOSHR/ 
   and mirrors may lag behind.

INSTALLATION
   To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

   or, if you use the CPAN shell, from the command line you can use:

   perl -MCPAN -e 'install "Proc::NiceSleep"'

DEPENDENCIES 
   This module requires no other non-standard perl modules, 
   but will perform with sub-second resolution only if Time::HiRes is 
   detected and supports it.

NAME
    Proc::NiceSleep - yield system in a quasi-intelligent fashion

SYNOPSIS
      use Proc::NiceSleep qw( sleepfactor minruntime maybesleep nice ); 
      nice(5);                 # lower our priority if our OS supports it 
      sleepfactor(2);          # sleep 2x as long as we run
      minruntime(2);           # run at least 2 seconds without sleep
      while($somecondition) {
        dosomething();
        $slept = maybesleep(); # sleep some amount of time if appropriate 
      }

DESCRIPTION
    Proc::NiceSleep is a Perl 5 module which defines subroutines to allow a
    process to yield use of the system in a method consistent with the
    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.

    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.

    By default Proc::NiceSleep expects to yield the process for an amount of
    time equal to the amount of time that process runs without sleeping
    (wallclock time). This is expressed by the default Sleep Factor of 1.0.

    The following functions can be imported from this module. No functions
    are exported by default.

    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 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 (signifying highest priority) to 20 (signifying lowest priority,
        'nicest').

    maybesleep ()
        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 we think maybesleep()
        actually slept for.

    sleepfactor ()
        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 1.

    minruntime ()
        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 1.

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

    Proc::NiceSleep is loosely modeled on Lincoln Stein's CGI.pm and on D.
    Wegscheid and other's Time::HiRes.pm.

EXPORT
    None by default.

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

CAVEATS
    sleepfactor() and minruntime() require numeric parameters if present,
    but no check is made that the passed scalar is a number.

    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, Proc::Queue, Proc::Swarm

COPYRIGHT
      Copyright (c) 2002 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
    Thanks to D. Wegscheid and others for Time::HiRes.pm. Thanks also to
    Michael G Schwern, Terrence Brannon, and David Alban for their valuable
    input.

