New upstream release.
[debian/cpulimit.git] / README
diff --git a/README b/README
index 6ffa82c..9c512eb 100644 (file)
--- a/README
+++ b/README
-Cpulimit 1.2
+README for LimitCPU
+==========================
 
-=======
-About:
-=======
+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.
 
-Cpulimit is a program that attempts to limit the cpu usage of a process (expressed in percentage, not in cpu time). This is useful to control batch jobs, when you don't want they eat too much cpu. It does not act on the nice value or other scheduling priority stuff, but on the real cpu usage. Also, it is able to adapt itself to the overall system load, dynamically and quickly.
-The control of the used cpu amount is done sending continue and stop POSIX signals to processes.
-All the children processes and threads of the specified process will share the same percent of cpu.
+LimitCPU is the direct child of CPUlimit, a creation of Angelo Marletta,
+which can be found at http://cpulimit.sourceforge.net.
 
-Developed by Angelo Marletta.
-Please send your feedback, bug reports, feature requests to marlonx80 at hotmail dot com.
 
-===========
-Changelog:
-===========
 
-- reorganization of the code, splitted in more source files
-- control function process_monitor() optimized by eliminating an unnecessary loop
-- experimental support for multiple control of children processes and threads
-  children detection algorithm seems heavy because of the amount of code,
-  but it's designed to be scalable when there are a lot of children processes
-- cpu count detection, i.e. if you have 4 cpu, it is possible to limit up to 400%
-- in order to avoid deadlock, cpulimit prevents to limit itself
-- option --path eliminated, use --exe instead both for absolute path and file name
-- deleted every setpriority(), (todo: set it just once)
-- minor enhancements and bugfixes
 
+Copying, License and Distribution
+===================================
 
-============================
-Get the latest source code:
-============================
+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.
 
-You can checkout the latest code from sourceforge Subversion repository, running:
+Copyright 2005, Angelo Marletta <marlonx80@hotmail.com>
+Copyright 2011-2012, Jesse Smith <jessefrgsmith@yahoo.ca>
 
-svn checkout https://cpulimit.svn.sourceforge.net/svnroot/cpulimit cpulimit
 
-Of course this is the development version, so you may experience bugs (please signal them!)
 
 
-==============
-Installation:
-==============
 
-Run 'make' and place the executable file 'cpulimit' wherever you want.
-Type 'cpulimit --help' to get documentation on available options.
+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.5.tar.gz
+
+Then we run the makefile.
+
+cd cpulimit-1.5
+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.
+
+The following example is useful for scripts where we want
+to launch a program and then immediately throttle it
+without knowing its process ID. The "$!" symbol refers to
+the last program run and the -b flag tells cpulimit to
+run in the background, returning control to the shell.
+
+/usr/bin/someapp &
+cpulimit -p $! -l 25 -b
+
+
+
+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.