src/niceload.pod

   1 #!/usr/bin/perl -w
   2
   3 # SPDX-FileCopyrightText: 2021-2024 Ole Tange, http://ole.tange.dk and Free Software and Foundation, Inc.
   4 # SPDX-License-Identifier: GFDL-1.3-or-later
   5 # SPDX-License-Identifier: CC-BY-SA-4.0
   6
   7 =head1 NAME
   8
   9 niceload - slow down a program when the load average is above a certain limit
  10
  11 =head1 SYNOPSIS
  12
  13 B<niceload> [-v] [-h] [-n nice] [-I io] [-L load] [-M mem] [-N]
  14 [--sensor program] [-t time] [-s time|-f factor]
  15 ( command | -p PID [-p PID ...] | --prg program )
  16
  17
  18 =head1 DESCRIPTION
  19
  20 GNU B<niceload> will slow down a program when the load average (or
  21 other system activity) is above a certain limit. When the limit is
  22 reached the program will be suspended for some time. Then resumed
  23 again for some time.  Then the load average is checked again and we
  24 start over.
  25
  26 Instead of load average B<niceload> can also look at disk I/O, amount
  27 of free memory, or swapping activity.
  28
  29 If the load is 3.00 then the default settings will run a program
  30 like this:
  31
  32 run 1 second, suspend (3.00-1.00) seconds, run 1 second, suspend
  33 (3.00-1.00) seconds, run 1 second, ...
  34
  35 =head1 OPTIONS
  36
  37 =over 9
  38
  39 =item B<-B>
  40
  41 =item B<--battery>
  42
  43 Suspend if the system is running on battery. Shorthand for:
  44 -l -1 --sensor 'cat /sys/class/power_supply/BAT0/status
  45 /proc/acpi/battery/BAT0/state 2>/dev/null | grep -i -q discharging;
  46 echo $?'
  47
  48
  49 =item B<-f> I<FACTOR>
  50
  51 =item B<--factor> I<FACTOR>
  52
  53 Suspend time factor. Dynamically set B<-s> as amount over limit *
  54 factor. Default is 1.
  55
  56
  57 =item B<-H>
  58
  59 =item B<--hard>
  60
  61 Hard limit. B<--hard> will suspend the process until the system is
  62 under the limits. The default is B<--soft>.
  63
  64
  65 =item B<--io> I<iolimit>
  66
  67 =item B<-I> I<iolimit>
  68
  69 Limit for I/O. The amount of disk I/O will be computed as a value 0 -
  70 10, where 0 is no I/O and 10 is at least one disk is 100% saturated.
  71
  72 B<--io> will set both B<--start-io> and B<--run-io>.
  73
  74
  75 =item B<--load> I<loadlimit>
  76
  77 =item B<-L> I<loadlimit>
  78
  79 Limit for load average.
  80
  81 B<--load> will set both B<--start-load> and B<--run-load>.
  82
  83
  84 =item B<--mem> I<memlimit>
  85
  86 =item B<-M> I<memlimit>
  87
  88 Limit for free memory. This is the amount of bytes available as free
  89 + cache. This limit is treated opposite other limits: If the system
  90 is above the limit the program will run, if it is below the limit the
  91 program will stop
  92
  93 I<memlimit> can be postfixed with K, M, G, T, or P which would
  94 multiply the size with 1024, 1048576, 1073741824, or 1099511627776
  95 respectively.
  96
  97 B<--mem> will set both B<--start-mem> and B<--run-mem>.
  98
  99
 100 =item B<--noswap>
 101
 102 =item B<-N>
 103
 104 No swapping. If the system is swapping both in and out it is a good
 105 indication that the system is memory stressed.
 106
 107 B<--noswap> is over limit if the system is swapping both in and out.
 108
 109 B<--noswap> will set both B<--start-noswap> and B<--run-noswap>.
 110
 111
 112 =item B<--net>
 113
 114 Shorthand for B<--nethops 3>.
 115
 116
 117 =item B<--nethops> I<h>
 118
 119 Network nice. Pause if the internet connection is overloaded.
 120
 121 B<niceload> finds a router I<h> hops closer to the internet. It
 122 B<ping>s this every second. If the latency is more than 50% bigger
 123 than the median, it is regarded as being over the limit.
 124
 125 B<--nethops> can be combined with B<--hard>. Without B<--hard> the
 126 program may be able to queue up so much traffic that it will take
 127 longer than the B<--suspend> time to clear it. B<--hard> is useful for
 128 traffic that does not break by being suspended for a longer time.
 129
 130 B<--nethops> can be combined with a high B<--suspend>. This way a
 131 program can be allowed to do a bit of traffic now and then. This is
 132 useful to keep the connection alive.
 133
 134
 135 =item B<-n> I<niceness>
 136
 137 =item B<--nice> I<niceness>
 138
 139 Sets niceness. See B<nice>(1).
 140
 141
 142 =item B<-p> I<PID>[,I<PID>]
 143
 144 =item B<--pid> I<PID>[,I<PID>]
 145
 146 Process IDs of processes to suspend. You can specify multiple process
 147 IDs with multiple B<-p> I<PID> or by separating the PIDs with comma.
 148
 149
 150 =item B<--prg> I<program>
 151
 152 =item B<--program> I<program>
 153
 154 Name of running program to suspend. You can specify multiple programs
 155 with multiple B<--prg> I<program>. If no processes with the name
 156 I<program> is found, B<niceload> with search for substrings containing
 157 I<program>.
 158
 159
 160 =item B<--quote>
 161
 162 =item B<-q>
 163
 164 Quote the command line. Useful if the command contains chars like *,
 165 $, >, and " that should not be interpreted by the shell.
 166
 167
 168 =item B<--run-io> I<iolimit>
 169
 170 =item B<--ri> I<iolimit>
 171
 172 =item B<--run-load> I<loadlimit>
 173
 174 =item B<--rl> I<loadlimit>
 175
 176 =item B<--run-mem> I<memlimit>
 177
 178 =item B<--rm> I<memlimit>
 179
 180 Run limit. The running program will be slowed down if the system is
 181 above the limit. See: B<--io>, B<--load>, B<--mem>, B<--noswap>.
 182
 183
 184 =item B<--sensor> I<sensor program>
 185
 186 Read sensor. Use I<sensor program> to read a sensor.
 187
 188 This will keep the CPU temperature below 80 deg C on GNU/Linux:
 189
 190   niceload -l 80000 -f 0.001 --sensor 'sort -n /sys/devices/platform/coretemp*/temp*_input' gzip *
 191
 192 This will stop if the disk space < 100000.
 193
 194   niceload -H -l -100000 --sensor "df . | awk '{ print \$4 }'" echo
 195
 196
 197 =item B<--start-io> I<iolimit>
 198
 199 =item B<--si> I<iolimit>
 200
 201 =item B<--start-load> I<loadlimit>
 202
 203 =item B<--sl> I<loadlimit>
 204
 205 =item B<--start-mem> I<memlimit>
 206
 207 =item B<--sm> I<memlimit>
 208
 209 Start limit. The program will not start until the system is below the
 210 limit. See: B<--io>, B<--load>, B<--mem>, B<--noswap>.
 211
 212
 213 =item B<--soft>
 214
 215 =item B<-S>
 216
 217 Soft limit. B<niceload> will suspend a process for a while and then
 218 let it run for a second thus only slowing down a process while the
 219 system is over one of the given limits. This is the default.
 220
 221
 222 =item B<--suspend> I<SEC>
 223
 224 =item B<-s> I<SEC>
 225
 226 Suspend time. Suspend the command this many seconds when the max load
 227 average is reached.
 228
 229
 230 =item B<--recheck> I<SEC>
 231
 232 =item B<-t> I<SEC>
 233
 234 Recheck load time. Sleep SEC seconds before checking load
 235 again. Default is 1 second.
 236
 237
 238 =item B<--verbose>
 239
 240 =item B<-v>
 241
 242 Verbose. Print some extra output on what is happening. Use B<-v> until
 243 you know what your are doing.
 244
 245 =back
 246
 247 =head1 EXAMPLE: See niceload in action
 248
 249 In terminal 1 run: top
 250
 251 In terminal 2 run:
 252
 253 B<niceload -q perl -e '$|=1;do{$l==$r or print "."; $l=$r}until(($r=time-$^T)>>B<50)'>
 254
 255 This will print a '.' every second for 50 seconds and eat a lot of
 256 CPU. When the load rises to 1.0 the process is suspended.
 257
 258
 259 =head1 EXAMPLE: Run updatedb
 260
 261 Running B<updatedb> can often starve the system for disk I/O and thus result in a high load.
 262
 263 Run B<updatedb> but suspend B<updatedb> if the load is above 2.00:
 264
 265 B<niceload -L 2 updatedb>
 266
 267
 268 =head1 EXAMPLE: Run rsync
 269
 270 B<rsync> can, just like B<updatedb>, starve the system for disk I/O
 271 and thus result in a high load.
 272
 273 Run B<rsync> but keep load below 3.4. If load reaches 7 sleep for
 274 (7-3.4)*12 seconds:
 275
 276 B<niceload -L 3.4 -f 12 rsync -Ha /home/ /backup/home/>
 277
 278
 279 =head1 EXAMPLE: Ensure enough disk cache
 280
 281 Assume the program B<foo> uses 2 GB files intensively. B<foo> will run
 282 fast if the files are in disk cache and be slow as a crawl if they are
 283 not in the cache.
 284
 285 To ensure 2 GB are reserved for disk cache run:
 286
 287 B<niceload --hard --run-mem 2g foo>
 288
 289 This will not guarantee that the 2 GB memory will be used for the
 290 files for B<foo>, but it will stop B<foo> if the memory for disk cache
 291 is too low.
 292
 293
 294 =head1 ENVIRONMENT VARIABLES
 295
 296 None. In future versions $NICELOAD will be able to contain default settings.
 297
 298 =head1 EXIT STATUS
 299
 300 Exit status should be the same as the command being run (untested).
 301
 302 =head1 REPORTING BUGS
 303
 304 Report bugs to <bug-parallel@gnu.org>.
 305
 306 =head1 AUTHOR
 307
 308 Copyright (C) 2004-11-19 Ole Tange, http://ole.tange.dk
 309
 310 Copyright (C) 2005-2010 Ole Tange, http://ole.tange.dk
 311
 312 Copyright (C) 2010-2024 Ole Tange, http://ole.tange.dk and Free
 313 Software Foundation, Inc.
 314
 315 =head1 LICENSE
 316
 317 This program is free software; you can redistribute it and/or modify
 318 it under the terms of the GNU General Public License as published by
 319 the Free Software Foundation; either version 3 of the License, or
 320 at your option any later version.
 321
 322 This program is distributed in the hope that it will be useful,
 323 but WITHOUT ANY WARRANTY; without even the implied warranty of
 324 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 325 GNU General Public License for more details.
 326
 327 You should have received a copy of the GNU General Public License
 328 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 329
 330 =head2 Documentation license I
 331
 332 Permission is granted to copy, distribute and/or modify this
 333 documentation under the terms of the GNU Free Documentation License,
 334 Version 1.3 or any later version published by the Free Software
 335 Foundation; with no Invariant Sections, with no Front-Cover Texts, and
 336 with no Back-Cover Texts.  A copy of the license is included in the
 337 file LICENSES/GFDL-1.3-or-later.txt.
 338
 339 =head2 Documentation license II
 340
 341 You are free:
 342
 343 =over 9
 344
 345 =item B<to Share>
 346
 347 to copy, distribute and transmit the work
 348
 349 =item B<to Remix>
 350
 351 to adapt the work
 352
 353 =back
 354
 355 Under the following conditions:
 356
 357 =over 9
 358
 359 =item B<Attribution>
 360
 361 You must attribute the work in the manner specified by the author or
 362 licensor (but not in any way that suggests that they endorse you or
 363 your use of the work).
 364
 365 =item B<Share Alike>
 366
 367 If you alter, transform, or build upon this work, you may distribute
 368 the resulting work only under the same, similar or a compatible
 369 license.
 370
 371 =back
 372
 373 With the understanding that:
 374
 375 =over 9
 376
 377 =item B<Waiver>
 378
 379 Any of the above conditions can be waived if you get permission from
 380 the copyright holder.
 381
 382 =item B<Public Domain>
 383
 384 Where the work or any of its elements is in the public domain under
 385 applicable law, that status is in no way affected by the license.
 386
 387 =item B<Other Rights>
 388
 389 In no way are any of the following rights affected by the license:
 390
 391 =over 2
 392
 393 =item *
 394
 395 Your fair dealing or fair use rights, or other applicable
 396 copyright exceptions and limitations;
 397
 398 =item *
 399
 400 The author's moral rights;
 401
 402 =item *
 403
 404 Rights other persons may have either in the work itself or in
 405 how the work is used, such as publicity or privacy rights.
 406
 407 =back
 408
 409 =back
 410
 411 =over 9
 412
 413 =item B<Notice>
 414
 415 For any reuse or distribution, you must make clear to others the
 416 license terms of this work.
 417
 418 =back
 419
 420 A copy of the full license is included in the file as
 421 LICENCES/CC-BY-SA-4.0.txt
 422
 423
 424 =head1 DEPENDENCIES
 425
 426 GNU B<niceload> uses Perl, and the Perl modules POSIX, and
 427 Getopt::Long.
 428
 429 =head1 SEE ALSO
 430
 431 B<parallel>(1), B<nice>(1), B<uptime>(1)
 432
 433 =cut