written by Radovan Garabík
e-mail: garabik@kassiopeia.juls.savba.sk

verynice is a nice(1)-like utility to throttle long running processes
beyond what can be achieved by nice(1), by repeatedly suspending and
resuming the process.


Requirements
------------

verynice is written in python3 and runs mainly on Linux systems - in
particular, it uses GNU ps to find out process children (it works on
Debian GNU/kFreeBSD).

If psutil is installed, verynice will take advantage of it and children
detection will be multiplatform.


Usage
-----

You can use verynice either to run a command (in this case it mimics nice(1)
usage), or to specify a PID of a running process.

Throttling is done by periodically suspending (via SIGSTOP) and resuming (via
SIGCONT) the process being throttled.

The parameter -n A/B is used to specify the throttling ratio. The process will
be let running for A seconds, then it will be stopped for B seconds, then again
running for A seconds etc... Floating point values can be used, e.g. -n 0.4/2
will make the process run 2 seconds and suspend for 0.4 seconds out of 2.4
second time interval.

If a single number is specified, B is taken to be 1, e.g. -n 3 will suspend the
process for 3 seconds and run it 1 second.

The default is 1/1, i.e. run the process 50% of the time in 2 second time
intervals.

You can use the -v parameter to increase verbosity - print to stderr $ when
process is stopped and = when run.

Use -vv to be more verbose, print timestamp for each stop/run action
to stderr. Use mostly with the -p option, otherwise it
will clobber screen output.

Use -vvv to be even more verbose. Useful for debugging.


Caveats
-------

verynice uses only pid's to identify processes, which can lead to a race
condition - if the child's pid is reused in the time between creation of list
of children and action (stopping or resuming), an incorrect process might be
throttled (but at most for one control period).


Examples
--------

$ verynice -n 2/0.5 scp server:bigfile local/

will copy `bigfile' from the remote server, repeatedly suspending the scp
command for 2 seconds, running it for 0.5 seconds, thus reducing the overall
download speed to one fifths and keeping the network connection responsive.


$ verynice -vv -n 3 -p 12345

will run the process (and all its children) with pid 12345 for 1 second,
suspend it for 3 seconds, i.e. keeping CPU load to one fourth, thus reducing
its power consumption and overheating.

$ verynice program

just use the default, run the program 50% of the time in 1 second intervals.

