README

   1 README for LimitCPU
   2 ==========================
   3
   4 LimitCPU is a program to throttle the CPU cycles used by other applications.
   5 LimitCPU will monitor a process and make sure its CPU usage stays at or
   6 below a given percentage. This can be used to make sure your system
   7 has plenty of CPU cycles available for other tasks. It can also be used
   8 to keep laptops cool in the face of CPU-hungry processes and for limiting
   9 virtual machines.
  10
  11 LimitCPU is the direct child of CPUlimit, a creation of Angelo Marletta,
  12 which can be found at http://cpulimit.sourceforge.net.
  13
  14
  15
  16
  17 Copying, License and Distribution
  18 ===================================
  19
  20 LimitCPU is licensed under the GNU General Public License (version 2).
  21 A copy of the license should be included with this program in a
  22 file named LICENSE.
  23
  24 Copyright 2005, Angelo Marletta <marlonx80@hotmail.com>
  25 Copyright 2011-2016, Jesse Smith <jessefrgsmith@yahoo.ca>
  26
  27
  28
  29
  30
  31 Where to get LimitCPU
  32 ==========================
  33
  34 The LimitCPU program can be aquired from http://limitcpu.sourceforge.net
  35
  36
  37
  38
  39 How to compile and install
  40 ===========================
  41
  42 Once you have downloaded a copy of LimitCPU building should be fairly
  43 straight forward. First we unpack the source code
  44
  45 tar zxf cpulimit-2.6.tar.gz
  46
  47 Then we run the makefile.
  48
  49 cd cpulimit-2.6
  50 make
  51
  52 This should produce the executable file "cpulimit". If you would like
  53 to install the program to make it available system-wide, run
  54
  55 make install
  56
  57
  58 Later should you wish to remove the program from your system, run
  59 the following command from the limitcpu directory
  60
  61 make deinstall
  62
  63
  64
  65 Note on compiling for non-Linux operating systems:
  66 LimitCPU can be compiled on FreeBSD and OS X (though at this time
  67 LimitCPU has not been tested and may not work properly on OS X).
  68 To compile LimitCPU on these platforms, instead of running "make"
  69 to build the executable, instead run either
  70
  71 make freebsd
  72 or
  73 make osx
  74
  75 in order to build on FreeBSD or OS X respectively.
  76
  77
  78
  79
  80
  81 Common usage
  82 ==========================
  83
  84 The LimitCPU program is generally used to throttle the CPU usage of
  85 one process. This can be done with the following command where
  86 12345 is the process ID number of a running program and 25 is the
  87 maximum percentage of the CPU we are willing to give that program
  88
  89 cpulimit -p 12345 -l 25
  90
  91 The above example will cause LimitCPU to keep an eye on the process
  92 with ID number 12345 until the program exits. Should we wish to
  93 run LimitCPU in the background we can use
  94
  95 cpulimit -p 12345 -l 25 -b
  96
  97 We can also limit running processes based on their name instead of
  98 their process ID, as in this example:
  99
 100 cpulimit --exe /usr/bin/bigexe --limit 50
 101
 102 The above example will keep an eye on "bigexe" and, if the application
 103 quits and another program called "bigexe" is run, LimitCPU will
 104 monitor the new process too. Should we wish to only track the first
 105 program and then exit, we can use
 106
 107 cpulimit --exe /usr/bin/bigexe --limit 50 -z
 108
 109 The "-z" flag tells LimitCPU to stop running once its target is
 110 no longer running itself.
 111
 112 The following example is useful for scripts where we want
 113 to launch a program and then immediately throttle it
 114 without knowing its process ID. The "$!" symbol refers to
 115 the last program run and the -b flag tells cpulimit to
 116 run in the background, returning control to the shell.
 117
 118 /usr/bin/someapp &
 119 cpulimit -p $! -l 25 -b
 120
 121
 122 Note: As of version 1.7 LimitCPU will attempt to guess the
 123 number of CPUs available on the machine and limit usage
 124 accordingly. For example, machines with dual-cores will
 125 be able to run processes with 1-200% limits. In case the
 126 automatic detection does not work, users can over-ride the
 127 number of CPUs LimitCPU thinks are available using the
 128 -c command line flag. For example
 129
 130 cpulimit -c 2 -p 12345 -l 150
 131
 132
 133 Commands can be launched by LimitCPU by appending the command
 134 to the end of of LimitCPU's argument list. For example, the
 135 following command will launch Firefox and limit it to 10% CPU
 136 usage:
 137
 138 cpulimit -l 10 firefox
 139
 140 Sometimes we wish to launch other programs and pass them parameters.
 141 To avoid confusing cpulimit as to which parameters are for it and
 142 which ones are for the child process, we can use the -- flag. For
 143 example, the following command launches Firefox in Private Browsing
 144 mode. To make sure the "-p" in Firefox's "-private" option does not
 145 confuse cpulimit, we use the -- flag.
 146
 147 cpulimit -l 25 -- firefox -private
 148
 149 In some special cases it may be desirable to kill a program
 150 instead of simple throttling its CPU usage. In these cases
 151 the -k flag can be used. For example, if we want to run a
 152 program called "yellow" and kill it when it goes over 50%
 153 CPU usage run the following:
 154
 155 cpulimit -l 50 -k yellow
 156
 157 The -k flag will terminate a process going over its limit,
 158 but what if we want to bring back the killed process to
 159 let it run again? For that purpose we have the -r flag. The
 160 -r flag causes a killed process to be restored.
 161
 162 cpulimit -l 50 -k -r yellow
 163
 164 The restore flag (-r) only works when the process to launch
 165 has been launched by cpulimit. For this reason it is necessary
 166 to specify the target program at the end of the command line
 167 as shown above.
 168
 169 LimitCPU, by default, will tell a watched process to continue
 170 running when LimitCPU terminates. This is accomplished by
 171 sending the watched process the SIGCONT signal just before
 172 LimitCPU exits. The user can specify an alternative signal to
 173 send the watched process when LimitCPU terminates. This is
 174 accomplished using the -s or --signal command line flag. Here
 175 is an example of terminating a watched process
 176
 177 cpulimit -l 25 -p 1234 -s SIGTERM
 178
 179 And here we accomplish the same thing using a numeric value
 180 instead of the written form of the signal.
 181
 182 cpulimit -l 25 -p 1234 --signal=15
 183
 184 LimitCPU can be used to watch not only one target process, but also
 185 child processes the target spawns. This means new processs the
 186 target creates will also be throttled. By default, LimitCPU
 187 only watches one target process and ignores children, but monitoring
 188 children can be enabled using the "-m" or "--monitor-forks" flag.
 189
 190 cpulimit -l 25 -p 1234 -m
 191
 192
 193
 194 Accessing the latest code
 195 ============================
 196
 197 For developers who would like to test or modify the latest
 198 LimitCPU code, the code is available in a Subversion (svn)
 199 repository. The code can be checked out using the command
 200
 201 svn checkout svn://svn.code.sf.net/p/limitcpu/code/ limitcpu-code
 202
 203
 204
 205
 206 Bugs and Feedback
 207 =============================
 208
 209 Should you have comments, questions, or bugs to report, please send
 210 an e-mail to jessefrgsmith@yahoo.ca with the word "LimitCPU" in the
 211 subject line.
 212