README for LimitCPU
==========================

LimitCPU is a program to throttle the CPU cycles used by other applications.
LimitCPU will monitor a process and make sure its CPU usage stays at or
below a given percentage. This can be used to make sure your system
has plenty of CPU cycles available for other tasks. It can also be used
to keep laptops cool in the face of CPU-hungry processes and for limiting
virtual machines.

LimitCPU is the direct child of CPUlimit, a creation of Angelo Marletta,
which can be found at http://cpulimit.sourceforge.net.




Copying, License and Distribution
===================================

LimitCPU is licensed under the GNU General Public License (version 2).
A copy of the license should be included with this program in a
file named LICENSE.





Where to get LimitCPU
==========================

The LimitCPU program can be aquired from http://limitcpu.sourceforge.net




How to compile and install
===========================

Once you have downloaded a copy of LimitCPU building should be fairly
straight forward. First we unpack the source code

tar zxf cpulimit-1.3.tar.gz

Then we run the makefile.

cd cpulimit-1.3
make

This should produce the executable file "cpulimit". If you would like
to install the program to make it available system-wide, run

make install


Later should you wish to remove the program from your system, run
the following command from the limitcpu directory

make deinstall



Common usage
==========================

The LimitCPU program is generally used to throttle the CPU usage of
one process. This can be done with the following command where
12345 is the process ID number of a running program and 25 is the
maximum percentage of the CPU we are willing to give that program

cpulimit -p 12345 -l 25

The above example will cause LimitCPU to keep an eye on the process
with ID number 12345 until the program exits. Should we wish to
run LimitCPU in the background we can use

cpulimit -p 12345 -l 25 -b

We can also limit running processes based on their name instead of
their process ID, as in this example:

cpulimit --exe /usr/bin/bigexe --limit 50

The above example will keep an eye on "bigexe" and, if the application
quits and another program called "bigexe" is run, LimitCPU will
monitor the new process too. Should we wish to only track the first
program and then exit, we can use 

cpulimit --exec /usr/bin/bigexe --limit 50 -z

The "-z" flag tells LimitCPU to stop running once its target is
no longer running itself.




Bugs and Feedback
=============================

Should you have comments, questions, or bugs to report, please send
an e-mail to jessefrgsmith@yahoo.ca with the word "LimitCPU" in the
subject line.

