.TH LOADWATCH 1 "July 2003"

.SH NAME
loadwatch \- run a program when machine is idle

.SH SYNOPSIS
\fBloadwatch\fR [\fIoptions\fR] \fB\-p\fR \fIpid\fR | [--]
\fIprog\fR [\fIargs\fR]
.br

.SH DESCRIPTION

\fBloadwatch\fR either spawns a child process \fIprog\fR with the
arguments \fIargs\fR and controls it with all its process group, or
takes control of an already running process with pid \fIpid\fR with all
its process group.

\fBloadwatch\fR allows the controlled processes to run while the load
average remains below \fIhigh_limit\fR. Every \fIdelay\fR seconds,
\fBloadwatch\fR checks the load average. If the load is above
\fIhigh_limit\fR, the child is suspended; the child is resumed when the
load falls below \fIlow_limit\fR.

.SH OPTIONS
A summary of options is included below.
.TP
\fB\-h\fR \fIhigh_limit\fR
A decimal value that sets the system load at which the child process will
be suspended. (Default: 1.25)
.TP
\fB\-l\fR \fIlow_limit\fR
A decimal value that sets the system load at which the child process will
be resumed. (Default: 0.25)
.TP
\fB\-d\fR \fIdelay\fR
An integral number of seconds that sets how often the system load will
be checked. (Default: 10)
.TP
\fB\-n\fR \fIcopies\fR
An integer value that sets the number of copies of \fIprog\fR to
run. (Default: 1)
.TP
\fB\-u\fR \fIfile\fR
Create a UNIX domain socket \fIfile\fR for use by \fBlw-ctl\fR.
.TP
\fB\-p\fR \fIpid\fR
The pid of the program that should be controlled by \fBloadwatch\fR
(with all its process group).

.SH "SEE ALSO"
lw-ctl(1), nice(1)

.SH BUGS
You should choose \fIlow_limit\fR and \fIhigh_limit\fR carefully. When
the load drops below \fIlow_limit\fR, the process(es) will be resumed,
and it should not, by itself, cause the load to raise above
\fIhigh_limit\fR, or the whole will oscillate, periodically suspending
and resuming the process(es).

Similarly, if several instances of loadwatch are running, they may
resume their processes at the same time, leading to oscillations if the
limits are not carefully chosen. Hence, each instance of loadwatch
affects every other instance on the computer, and should not be
considered in isolation.

.SH AUTHOR
This manual page was written by Dale E. Martin <dmartin@debian.org>,
for the Debian GNU/Linux system (but may be used by others). It was
then updated by Nicolas Boullis <nboullis@debian.org>.