NAME

Proc::NiceSleep - Perl module to have a process yield use of the system in a quasi-intelligent fashion, consistent with a runtime-specified policy.

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 what value it believes the priority was set to. If no parameter is passed, nice() attempts to query the operating system for the priority of the process and returns. If your OS doesn't support priorities then nice() will likely always return 0.

The exact nice() values returned, and their meanings to the system, are system dependent, but usually range from -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 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>

REVISION

$Log: NiceSleep.pm,v $ Revision 1.17 2002/02/19 16:03:56 root doc changes, moved private func

Revision 1.16 2002/02/19 07:22:36 root version bump, tiny changes.

Revision 1.15 2002/02/18 22:18:28 root fix email address, unindent Log

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

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.