Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`resource` --- Resource usage information |
| 2 | ============================================== |
| 3 | |
| 4 | .. module:: resource |
| 5 | :platform: Unix |
| 6 | :synopsis: An interface to provide resource usage information on the current process. |
| 7 | .. moduleauthor:: Jeremy Hylton <jeremy@alum.mit.edu> |
| 8 | .. sectionauthor:: Jeremy Hylton <jeremy@alum.mit.edu> |
| 9 | |
| 10 | |
| 11 | This module provides basic mechanisms for measuring and controlling system |
| 12 | resources utilized by a program. |
| 13 | |
| 14 | Symbolic constants are used to specify particular system resources and to |
| 15 | request usage information about either the current process or its children. |
| 16 | |
Benjamin Peterson | 2122cf7 | 2011-12-10 17:50:22 -0500 | [diff] [blame] | 17 | An :exc:`OSError` is raised on syscall failure. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 18 | |
| 19 | |
| 20 | .. exception:: error |
| 21 | |
Benjamin Peterson | 2122cf7 | 2011-12-10 17:50:22 -0500 | [diff] [blame] | 22 | A deprecated alias of :exc:`OSError`. |
| 23 | |
| 24 | .. versionchanged:: 3.3 |
| 25 | Following :pep:`3151`, this class was made an alias of :exc:`OSError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | |
| 27 | |
| 28 | Resource Limits |
| 29 | --------------- |
| 30 | |
| 31 | Resources usage can be limited using the :func:`setrlimit` function described |
| 32 | below. Each resource is controlled by a pair of limits: a soft limit and a hard |
| 33 | limit. The soft limit is the current limit, and may be lowered or raised by a |
| 34 | process over time. The soft limit can never exceed the hard limit. The hard |
| 35 | limit can be lowered to any value greater than the soft limit, but not raised. |
| 36 | (Only processes with the effective UID of the super-user can raise a hard |
| 37 | limit.) |
| 38 | |
| 39 | The specific resources that can be limited are system dependent. They are |
| 40 | described in the :manpage:`getrlimit(2)` man page. The resources listed below |
| 41 | are supported when the underlying operating system supports them; resources |
| 42 | which cannot be checked or controlled by the operating system are not defined in |
| 43 | this module for those platforms. |
| 44 | |
| 45 | |
R David Murray | bdf940d | 2013-04-20 13:37:34 -0400 | [diff] [blame] | 46 | .. data:: RLIM_INFINITY |
| 47 | |
Senthil Kumaran | b4760ef | 2015-06-14 17:35:37 -0700 | [diff] [blame] | 48 | Constant used to represent the limit for an unlimited resource. |
R David Murray | bdf940d | 2013-04-20 13:37:34 -0400 | [diff] [blame] | 49 | |
| 50 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 51 | .. function:: getrlimit(resource) |
| 52 | |
| 53 | Returns a tuple ``(soft, hard)`` with the current soft and hard limits of |
| 54 | *resource*. Raises :exc:`ValueError` if an invalid resource is specified, or |
| 55 | :exc:`error` if the underlying system call fails unexpectedly. |
| 56 | |
| 57 | |
| 58 | .. function:: setrlimit(resource, limits) |
| 59 | |
| 60 | Sets new limits of consumption of *resource*. The *limits* argument must be a |
| 61 | tuple ``(soft, hard)`` of two integers describing the new limits. A value of |
R David Murray | bdf940d | 2013-04-20 13:37:34 -0400 | [diff] [blame] | 62 | :data:`~resource.RLIM_INFINITY` can be used to request a limit that is |
| 63 | unlimited. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 64 | |
| 65 | Raises :exc:`ValueError` if an invalid resource is specified, if the new soft |
R David Murray | bdf940d | 2013-04-20 13:37:34 -0400 | [diff] [blame] | 66 | limit exceeds the hard limit, or if a process tries to raise its hard limit. |
| 67 | Specifying a limit of :data:`~resource.RLIM_INFINITY` when the hard or |
| 68 | system limit for that resource is not unlimited will result in a |
| 69 | :exc:`ValueError`. A process with the effective UID of super-user can |
| 70 | request any valid limit value, including unlimited, but :exc:`ValueError` |
| 71 | will still be raised if the requested limit exceeds the system imposed |
| 72 | limit. |
| 73 | |
| 74 | ``setrlimit`` may also raise :exc:`error` if the underlying system call |
| 75 | fails. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 76 | |
Christian Heimes | b7bd5df | 2013-10-22 11:21:54 +0200 | [diff] [blame] | 77 | .. function:: prlimit(pid, resource[, limits]) |
| 78 | |
| 79 | Combines :func:`setrlimit` and :func:`getrlimit` in one function and |
| 80 | supports to get and set the resources limits of an arbitrary process. If |
| 81 | *pid* is 0, then the call applies to the current process. *resource* and |
| 82 | *limits* have the same meaning as in :func:`setrlimit`, except that |
| 83 | *limits* is optional. |
| 84 | |
| 85 | When *limits* is not given the function returns the *resource* limit of the |
| 86 | process *pid*. When *limits* is given the *resource* limit of the process is |
| 87 | set and the former resource limit is returned. |
| 88 | |
| 89 | Raises :exc:`ProcessLookupError` when *pid* can't be found and |
| 90 | :exc:`PermissionError` when the user doesn't have ``CAP_SYS_RESOURCE`` for |
| 91 | the process. |
| 92 | |
Christian Heimes | c4a4b34 | 2013-10-25 08:31:19 +0200 | [diff] [blame] | 93 | Availability: Linux 2.6.36 or later with glibc 2.13 or later |
Christian Heimes | b7bd5df | 2013-10-22 11:21:54 +0200 | [diff] [blame] | 94 | |
| 95 | .. versionadded:: 3.4 |
| 96 | |
| 97 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 98 | These symbols define resources whose consumption can be controlled using the |
| 99 | :func:`setrlimit` and :func:`getrlimit` functions described below. The values of |
| 100 | these symbols are exactly the constants used by C programs. |
| 101 | |
| 102 | The Unix man page for :manpage:`getrlimit(2)` lists the available resources. |
| 103 | Note that not all systems use the same symbol or same value to denote the same |
| 104 | resource. This module does not attempt to mask platform differences --- symbols |
| 105 | not defined for a platform will not be available from this module on that |
| 106 | platform. |
| 107 | |
| 108 | |
| 109 | .. data:: RLIMIT_CORE |
| 110 | |
| 111 | The maximum size (in bytes) of a core file that the current process can create. |
| 112 | This may result in the creation of a partial core file if a larger core would be |
| 113 | required to contain the entire process image. |
| 114 | |
| 115 | |
| 116 | .. data:: RLIMIT_CPU |
| 117 | |
| 118 | The maximum amount of processor time (in seconds) that a process can use. If |
| 119 | this limit is exceeded, a :const:`SIGXCPU` signal is sent to the process. (See |
| 120 | the :mod:`signal` module documentation for information about how to catch this |
| 121 | signal and do something useful, e.g. flush open files to disk.) |
| 122 | |
| 123 | |
| 124 | .. data:: RLIMIT_FSIZE |
| 125 | |
| 126 | The maximum size of a file which the process may create. This only affects the |
| 127 | stack of the main thread in a multi-threaded process. |
| 128 | |
| 129 | |
| 130 | .. data:: RLIMIT_DATA |
| 131 | |
| 132 | The maximum size (in bytes) of the process's heap. |
| 133 | |
| 134 | |
| 135 | .. data:: RLIMIT_STACK |
| 136 | |
| 137 | The maximum size (in bytes) of the call stack for the current process. |
| 138 | |
| 139 | |
| 140 | .. data:: RLIMIT_RSS |
| 141 | |
| 142 | The maximum resident set size that should be made available to the process. |
| 143 | |
| 144 | |
| 145 | .. data:: RLIMIT_NPROC |
| 146 | |
| 147 | The maximum number of processes the current process may create. |
| 148 | |
| 149 | |
| 150 | .. data:: RLIMIT_NOFILE |
| 151 | |
| 152 | The maximum number of open file descriptors for the current process. |
| 153 | |
| 154 | |
| 155 | .. data:: RLIMIT_OFILE |
| 156 | |
| 157 | The BSD name for :const:`RLIMIT_NOFILE`. |
| 158 | |
| 159 | |
| 160 | .. data:: RLIMIT_MEMLOCK |
| 161 | |
| 162 | The maximum address space which may be locked in memory. |
| 163 | |
| 164 | |
| 165 | .. data:: RLIMIT_VMEM |
| 166 | |
| 167 | The largest area of mapped memory which the process may occupy. |
| 168 | |
| 169 | |
| 170 | .. data:: RLIMIT_AS |
| 171 | |
| 172 | The maximum area (in bytes) of address space which may be taken by the process. |
| 173 | |
| 174 | |
Christian Heimes | 6fc79bf | 2013-10-22 11:09:27 +0200 | [diff] [blame] | 175 | .. data:: RLIMIT_MSGQUEUE |
| 176 | |
| 177 | The number of bytes that can be allocated for POSIX message queues. |
| 178 | |
| 179 | Availability: Linux 2.6.8 or later. |
| 180 | |
| 181 | .. versionadded:: 3.4 |
| 182 | |
| 183 | |
| 184 | .. data:: RLIMIT_NICE |
| 185 | |
| 186 | The ceiling for the process's nice level (calculated as 20 - rlim_cur). |
| 187 | |
| 188 | Availability: Linux 2.6.12 or later. |
| 189 | |
| 190 | .. versionadded:: 3.4 |
| 191 | |
| 192 | |
| 193 | .. data:: RLIMIT_RTPRIO |
| 194 | |
| 195 | The ceiling of the real-time priority. |
| 196 | |
| 197 | Availability: Linux 2.6.12 or later. |
| 198 | |
| 199 | .. versionadded:: 3.4 |
| 200 | |
| 201 | |
| 202 | .. data:: RLIMIT_RTTIME |
| 203 | |
| 204 | The time limit (in microseconds) on CPU time that a process can spend |
| 205 | under real-time scheduling without making a blocking syscall. |
| 206 | |
| 207 | Availability: Linux 2.6.25 or later. |
| 208 | |
| 209 | .. versionadded:: 3.4 |
| 210 | |
| 211 | |
| 212 | .. data:: RLIMIT_SIGPENDING |
| 213 | |
| 214 | The number of signals which the process may queue. |
| 215 | |
| 216 | Availability: Linux 2.6.8 or later. |
| 217 | |
| 218 | .. versionadded:: 3.4 |
| 219 | |
Christian Heimes | 5bb414d | 2013-12-08 14:35:55 +0100 | [diff] [blame] | 220 | .. data:: RLIMIT_SBSIZE |
| 221 | |
| 222 | The maximum size (in bytes) of socket buffer usage for this user. |
| 223 | This limits the amount of network memory, and hence the amount of mbufs, |
| 224 | that this user may hold at any time. |
| 225 | |
| 226 | Availability: FreeBSD 9 or later. |
| 227 | |
| 228 | .. versionadded:: 3.4 |
| 229 | |
| 230 | .. data:: RLIMIT_SWAP |
| 231 | |
| 232 | The maximum size (in bytes) of the swap space that may be reserved or |
| 233 | used by all of this user id's processes. |
| 234 | This limit is enforced only if bit 1 of the vm.overcommit sysctl is set. |
| 235 | Please see :manpage:`tuning(7)` for a complete description of this sysctl. |
| 236 | |
| 237 | Availability: FreeBSD 9 or later. |
| 238 | |
| 239 | .. versionadded:: 3.4 |
| 240 | |
| 241 | .. data:: RLIMIT_NPTS |
| 242 | |
| 243 | The maximum number of pseudo-terminals created by this user id. |
| 244 | |
| 245 | Availability: FreeBSD 9 or later. |
| 246 | |
| 247 | .. versionadded:: 3.4 |
Christian Heimes | 6fc79bf | 2013-10-22 11:09:27 +0200 | [diff] [blame] | 248 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 249 | Resource Usage |
| 250 | -------------- |
| 251 | |
| 252 | These functions are used to retrieve resource usage information: |
| 253 | |
| 254 | |
| 255 | .. function:: getrusage(who) |
| 256 | |
| 257 | This function returns an object that describes the resources consumed by either |
| 258 | the current process or its children, as specified by the *who* parameter. The |
| 259 | *who* parameter should be specified using one of the :const:`RUSAGE_\*` |
| 260 | constants described below. |
| 261 | |
| 262 | The fields of the return value each describe how a particular system resource |
| 263 | has been used, e.g. amount of time spent running is user mode or number of times |
| 264 | the process was swapped out of main memory. Some values are dependent on the |
| 265 | clock tick internal, e.g. the amount of memory the process is using. |
| 266 | |
| 267 | For backward compatibility, the return value is also accessible as a tuple of 16 |
| 268 | elements. |
| 269 | |
| 270 | The fields :attr:`ru_utime` and :attr:`ru_stime` of the return value are |
| 271 | floating point values representing the amount of time spent executing in user |
| 272 | mode and the amount of time spent executing in system mode, respectively. The |
| 273 | remaining values are integers. Consult the :manpage:`getrusage(2)` man page for |
| 274 | detailed information about these values. A brief summary is presented here: |
| 275 | |
| 276 | +--------+---------------------+-------------------------------+ |
| 277 | | Index | Field | Resource | |
| 278 | +========+=====================+===============================+ |
| 279 | | ``0`` | :attr:`ru_utime` | time in user mode (float) | |
| 280 | +--------+---------------------+-------------------------------+ |
| 281 | | ``1`` | :attr:`ru_stime` | time in system mode (float) | |
| 282 | +--------+---------------------+-------------------------------+ |
| 283 | | ``2`` | :attr:`ru_maxrss` | maximum resident set size | |
| 284 | +--------+---------------------+-------------------------------+ |
| 285 | | ``3`` | :attr:`ru_ixrss` | shared memory size | |
| 286 | +--------+---------------------+-------------------------------+ |
| 287 | | ``4`` | :attr:`ru_idrss` | unshared memory size | |
| 288 | +--------+---------------------+-------------------------------+ |
| 289 | | ``5`` | :attr:`ru_isrss` | unshared stack size | |
| 290 | +--------+---------------------+-------------------------------+ |
| 291 | | ``6`` | :attr:`ru_minflt` | page faults not requiring I/O | |
| 292 | +--------+---------------------+-------------------------------+ |
| 293 | | ``7`` | :attr:`ru_majflt` | page faults requiring I/O | |
| 294 | +--------+---------------------+-------------------------------+ |
| 295 | | ``8`` | :attr:`ru_nswap` | number of swap outs | |
| 296 | +--------+---------------------+-------------------------------+ |
| 297 | | ``9`` | :attr:`ru_inblock` | block input operations | |
| 298 | +--------+---------------------+-------------------------------+ |
| 299 | | ``10`` | :attr:`ru_oublock` | block output operations | |
| 300 | +--------+---------------------+-------------------------------+ |
| 301 | | ``11`` | :attr:`ru_msgsnd` | messages sent | |
| 302 | +--------+---------------------+-------------------------------+ |
| 303 | | ``12`` | :attr:`ru_msgrcv` | messages received | |
| 304 | +--------+---------------------+-------------------------------+ |
| 305 | | ``13`` | :attr:`ru_nsignals` | signals received | |
| 306 | +--------+---------------------+-------------------------------+ |
| 307 | | ``14`` | :attr:`ru_nvcsw` | voluntary context switches | |
| 308 | +--------+---------------------+-------------------------------+ |
| 309 | | ``15`` | :attr:`ru_nivcsw` | involuntary context switches | |
| 310 | +--------+---------------------+-------------------------------+ |
| 311 | |
| 312 | This function will raise a :exc:`ValueError` if an invalid *who* parameter is |
| 313 | specified. It may also raise :exc:`error` exception in unusual circumstances. |
| 314 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 315 | |
| 316 | .. function:: getpagesize() |
| 317 | |
| 318 | Returns the number of bytes in a system page. (This need not be the same as the |
| 319 | hardware page size.) This function is useful for determining the number of bytes |
| 320 | of memory a process is using. The third element of the tuple returned by |
| 321 | :func:`getrusage` describes memory usage in pages; multiplying by page size |
| 322 | produces number of bytes. |
| 323 | |
| 324 | The following :const:`RUSAGE_\*` symbols are passed to the :func:`getrusage` |
| 325 | function to specify which processes information should be provided for. |
| 326 | |
| 327 | |
| 328 | .. data:: RUSAGE_SELF |
| 329 | |
Antoine Pitrou | b6d4ee5 | 2010-11-17 16:19:35 +0000 | [diff] [blame] | 330 | Pass to :func:`getrusage` to request resources consumed by the calling |
| 331 | process, which is the sum of resources used by all threads in the process. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 332 | |
| 333 | |
| 334 | .. data:: RUSAGE_CHILDREN |
| 335 | |
Antoine Pitrou | b6d4ee5 | 2010-11-17 16:19:35 +0000 | [diff] [blame] | 336 | Pass to :func:`getrusage` to request resources consumed by child processes |
| 337 | of the calling process which have been terminated and waited for. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 338 | |
| 339 | |
| 340 | .. data:: RUSAGE_BOTH |
| 341 | |
| 342 | Pass to :func:`getrusage` to request resources consumed by both the current |
| 343 | process and child processes. May not be available on all systems. |
| 344 | |
Antoine Pitrou | b6d4ee5 | 2010-11-17 16:19:35 +0000 | [diff] [blame] | 345 | |
| 346 | .. data:: RUSAGE_THREAD |
| 347 | |
| 348 | Pass to :func:`getrusage` to request resources consumed by the current |
| 349 | thread. May not be available on all systems. |
| 350 | |
| 351 | .. versionadded:: 3.2 |