Proc/NiceSleep version 0.54

STATUS
  This is BETA software.  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, and
  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( :all );
     nice(5);                  # lower our priority, if our OS supports it
     max_load(1.1);            # max load we allow, if Sys::CpuLoad found
     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 appropriate
     }

 GETTING HELP
   If you have questions about Proc::NiceSleep, you can get help from the
   [email protected] mailing list. 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 work 'subscribe' in the email to

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

DESCRIPTION
   Proc::NiceSleep is a Perl 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.

   By default Proc::NiceSleep expects to yield the process for one tenth
   the amount of time the process runs without sleeping. 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. 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 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 1 second.

   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. Setting
       the minimum sleep time to zero (which is also the default value)
       will disable this feature.

   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, <[email protected]>

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.