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