mirror of https://github.com/python/cpython
386 lines
13 KiB
ReStructuredText
386 lines
13 KiB
ReStructuredText
:mod:`!resource` --- Resource usage information
|
|
===============================================
|
|
|
|
.. module:: resource
|
|
:platform: Unix
|
|
:synopsis: An interface to provide resource usage information on the current process.
|
|
|
|
.. moduleauthor:: Jeremy Hylton <jeremy@alum.mit.edu>
|
|
.. sectionauthor:: Jeremy Hylton <jeremy@alum.mit.edu>
|
|
|
|
--------------
|
|
|
|
This module provides basic mechanisms for measuring and controlling system
|
|
resources utilized by a program.
|
|
|
|
.. availability:: Unix, not WASI.
|
|
|
|
Symbolic constants are used to specify particular system resources and to
|
|
request usage information about either the current process or its children.
|
|
|
|
An :exc:`OSError` is raised on syscall failure.
|
|
|
|
|
|
.. exception:: error
|
|
|
|
A deprecated alias of :exc:`OSError`.
|
|
|
|
.. versionchanged:: 3.3
|
|
Following :pep:`3151`, this class was made an alias of :exc:`OSError`.
|
|
|
|
|
|
Resource Limits
|
|
---------------
|
|
|
|
Resources usage can be limited using the :func:`setrlimit` function described
|
|
below. Each resource is controlled by a pair of limits: a soft limit and a hard
|
|
limit. The soft limit is the current limit, and may be lowered or raised by a
|
|
process over time. The soft limit can never exceed the hard limit. The hard
|
|
limit can be lowered to any value greater than the soft limit, but not raised.
|
|
(Only processes with the effective UID of the super-user can raise a hard
|
|
limit.)
|
|
|
|
The specific resources that can be limited are system dependent. They are
|
|
described in the :manpage:`getrlimit(2)` man page. The resources listed below
|
|
are supported when the underlying operating system supports them; resources
|
|
which cannot be checked or controlled by the operating system are not defined in
|
|
this module for those platforms.
|
|
|
|
|
|
.. data:: RLIM_INFINITY
|
|
|
|
Constant used to represent the limit for an unlimited resource.
|
|
|
|
|
|
.. function:: getrlimit(resource)
|
|
|
|
Returns a tuple ``(soft, hard)`` with the current soft and hard limits of
|
|
*resource*. Raises :exc:`ValueError` if an invalid resource is specified, or
|
|
:exc:`error` if the underlying system call fails unexpectedly.
|
|
|
|
|
|
.. function:: setrlimit(resource, limits)
|
|
|
|
Sets new limits of consumption of *resource*. The *limits* argument must be a
|
|
tuple ``(soft, hard)`` of two integers describing the new limits. A value of
|
|
:data:`~resource.RLIM_INFINITY` can be used to request a limit that is
|
|
unlimited.
|
|
|
|
Raises :exc:`ValueError` if an invalid resource is specified, if the new soft
|
|
limit exceeds the hard limit, or if a process tries to raise its hard limit.
|
|
Specifying a limit of :data:`~resource.RLIM_INFINITY` when the hard or
|
|
system limit for that resource is not unlimited will result in a
|
|
:exc:`ValueError`. A process with the effective UID of super-user can
|
|
request any valid limit value, including unlimited, but :exc:`ValueError`
|
|
will still be raised if the requested limit exceeds the system imposed
|
|
limit.
|
|
|
|
``setrlimit`` may also raise :exc:`error` if the underlying system call
|
|
fails.
|
|
|
|
VxWorks only supports setting :data:`RLIMIT_NOFILE`.
|
|
|
|
.. audit-event:: resource.setrlimit resource,limits resource.setrlimit
|
|
|
|
|
|
.. function:: prlimit(pid, resource[, limits])
|
|
|
|
Combines :func:`setrlimit` and :func:`getrlimit` in one function and
|
|
supports to get and set the resources limits of an arbitrary process. If
|
|
*pid* is 0, then the call applies to the current process. *resource* and
|
|
*limits* have the same meaning as in :func:`setrlimit`, except that
|
|
*limits* is optional.
|
|
|
|
When *limits* is not given the function returns the *resource* limit of the
|
|
process *pid*. When *limits* is given the *resource* limit of the process is
|
|
set and the former resource limit is returned.
|
|
|
|
Raises :exc:`ProcessLookupError` when *pid* can't be found and
|
|
:exc:`PermissionError` when the user doesn't have ``CAP_SYS_RESOURCE`` for
|
|
the process.
|
|
|
|
.. audit-event:: resource.prlimit pid,resource,limits resource.prlimit
|
|
|
|
.. availability:: Linux >= 2.6.36 with glibc >= 2.13.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
|
|
These symbols define resources whose consumption can be controlled using the
|
|
:func:`setrlimit` and :func:`getrlimit` functions described below. The values of
|
|
these symbols are exactly the constants used by C programs.
|
|
|
|
The Unix man page for :manpage:`getrlimit(2)` lists the available resources.
|
|
Note that not all systems use the same symbol or same value to denote the same
|
|
resource. This module does not attempt to mask platform differences --- symbols
|
|
not defined for a platform will not be available from this module on that
|
|
platform.
|
|
|
|
|
|
.. data:: RLIMIT_CORE
|
|
|
|
The maximum size (in bytes) of a core file that the current process can create.
|
|
This may result in the creation of a partial core file if a larger core would be
|
|
required to contain the entire process image.
|
|
|
|
|
|
.. data:: RLIMIT_CPU
|
|
|
|
The maximum amount of processor time (in seconds) that a process can use. If
|
|
this limit is exceeded, a :const:`SIGXCPU` signal is sent to the process. (See
|
|
the :mod:`signal` module documentation for information about how to catch this
|
|
signal and do something useful, e.g. flush open files to disk.)
|
|
|
|
|
|
.. data:: RLIMIT_FSIZE
|
|
|
|
The maximum size of a file which the process may create.
|
|
|
|
|
|
.. data:: RLIMIT_DATA
|
|
|
|
The maximum size (in bytes) of the process's heap.
|
|
|
|
|
|
.. data:: RLIMIT_STACK
|
|
|
|
The maximum size (in bytes) of the call stack for the current process. This only
|
|
affects the stack of the main thread in a multi-threaded process.
|
|
|
|
|
|
.. data:: RLIMIT_RSS
|
|
|
|
The maximum resident set size that should be made available to the process.
|
|
|
|
|
|
.. data:: RLIMIT_NPROC
|
|
|
|
The maximum number of processes the current process may create.
|
|
|
|
|
|
.. data:: RLIMIT_NOFILE
|
|
|
|
The maximum number of open file descriptors for the current process.
|
|
|
|
|
|
.. data:: RLIMIT_OFILE
|
|
|
|
The BSD name for :const:`RLIMIT_NOFILE`.
|
|
|
|
|
|
.. data:: RLIMIT_MEMLOCK
|
|
|
|
The maximum address space which may be locked in memory.
|
|
|
|
|
|
.. data:: RLIMIT_VMEM
|
|
|
|
The largest area of mapped memory which the process may occupy.
|
|
|
|
.. availability:: FreeBSD >= 11.
|
|
|
|
|
|
.. data:: RLIMIT_AS
|
|
|
|
The maximum area (in bytes) of address space which may be taken by the process.
|
|
|
|
|
|
.. data:: RLIMIT_MSGQUEUE
|
|
|
|
The number of bytes that can be allocated for POSIX message queues.
|
|
|
|
.. availability:: Linux >= 2.6.8.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
|
|
.. data:: RLIMIT_NICE
|
|
|
|
The ceiling for the process's nice level (calculated as 20 - rlim_cur).
|
|
|
|
.. availability:: Linux >= 2.6.12.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
|
|
.. data:: RLIMIT_RTPRIO
|
|
|
|
The ceiling of the real-time priority.
|
|
|
|
.. availability:: Linux >= 2.6.12.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
|
|
.. data:: RLIMIT_RTTIME
|
|
|
|
The time limit (in microseconds) on CPU time that a process can spend
|
|
under real-time scheduling without making a blocking syscall.
|
|
|
|
.. availability:: Linux >= 2.6.25.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
|
|
.. data:: RLIMIT_SIGPENDING
|
|
|
|
The number of signals which the process may queue.
|
|
|
|
.. availability:: Linux >= 2.6.8.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
.. data:: RLIMIT_SBSIZE
|
|
|
|
The maximum size (in bytes) of socket buffer usage for this user.
|
|
This limits the amount of network memory, and hence the amount of mbufs,
|
|
that this user may hold at any time.
|
|
|
|
.. availability:: FreeBSD.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
.. data:: RLIMIT_SWAP
|
|
|
|
The maximum size (in bytes) of the swap space that may be reserved or
|
|
used by all of this user id's processes.
|
|
This limit is enforced only if bit 1 of the vm.overcommit sysctl is set.
|
|
Please see
|
|
`tuning(7) <https://man.freebsd.org/cgi/man.cgi?query=tuning&sektion=7>`__
|
|
for a complete description of this sysctl.
|
|
|
|
.. availability:: FreeBSD.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
.. data:: RLIMIT_NPTS
|
|
|
|
The maximum number of pseudo-terminals created by this user id.
|
|
|
|
.. availability:: FreeBSD.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
.. data:: RLIMIT_KQUEUES
|
|
|
|
The maximum number of kqueues this user id is allowed to create.
|
|
|
|
.. availability:: FreeBSD >= 11.
|
|
|
|
.. versionadded:: 3.10
|
|
|
|
Resource Usage
|
|
--------------
|
|
|
|
These functions are used to retrieve resource usage information:
|
|
|
|
|
|
.. function:: getrusage(who)
|
|
|
|
This function returns an object that describes the resources consumed by either
|
|
the current process or its children, as specified by the *who* parameter. The
|
|
*who* parameter should be specified using one of the :const:`!RUSAGE_\*`
|
|
constants described below.
|
|
|
|
A simple example::
|
|
|
|
from resource import *
|
|
import time
|
|
|
|
# a non CPU-bound task
|
|
time.sleep(3)
|
|
print(getrusage(RUSAGE_SELF))
|
|
|
|
# a CPU-bound task
|
|
for i in range(10 ** 8):
|
|
_ = 1 + 1
|
|
print(getrusage(RUSAGE_SELF))
|
|
|
|
The fields of the return value each describe how a particular system resource
|
|
has been used, e.g. amount of time spent running is user mode or number of times
|
|
the process was swapped out of main memory. Some values are dependent on the
|
|
clock tick internal, e.g. the amount of memory the process is using.
|
|
|
|
For backward compatibility, the return value is also accessible as a tuple of 16
|
|
elements.
|
|
|
|
The fields :attr:`ru_utime` and :attr:`ru_stime` of the return value are
|
|
floating point values representing the amount of time spent executing in user
|
|
mode and the amount of time spent executing in system mode, respectively. The
|
|
remaining values are integers. Consult the :manpage:`getrusage(2)` man page for
|
|
detailed information about these values. A brief summary is presented here:
|
|
|
|
+--------+---------------------+---------------------------------------+
|
|
| Index | Field | Resource |
|
|
+========+=====================+=======================================+
|
|
| ``0`` | :attr:`ru_utime` | time in user mode (float seconds) |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``1`` | :attr:`ru_stime` | time in system mode (float seconds) |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``2`` | :attr:`ru_maxrss` | maximum resident set size |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``3`` | :attr:`ru_ixrss` | shared memory size |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``4`` | :attr:`ru_idrss` | unshared memory size |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``5`` | :attr:`ru_isrss` | unshared stack size |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``6`` | :attr:`ru_minflt` | page faults not requiring I/O |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``7`` | :attr:`ru_majflt` | page faults requiring I/O |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``8`` | :attr:`ru_nswap` | number of swap outs |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``9`` | :attr:`ru_inblock` | block input operations |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``10`` | :attr:`ru_oublock` | block output operations |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``11`` | :attr:`ru_msgsnd` | messages sent |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``12`` | :attr:`ru_msgrcv` | messages received |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``13`` | :attr:`ru_nsignals` | signals received |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``14`` | :attr:`ru_nvcsw` | voluntary context switches |
|
|
+--------+---------------------+---------------------------------------+
|
|
| ``15`` | :attr:`ru_nivcsw` | involuntary context switches |
|
|
+--------+---------------------+---------------------------------------+
|
|
|
|
This function will raise a :exc:`ValueError` if an invalid *who* parameter is
|
|
specified. It may also raise :exc:`error` exception in unusual circumstances.
|
|
|
|
|
|
.. function:: getpagesize()
|
|
|
|
Returns the number of bytes in a system page. (This need not be the same as the
|
|
hardware page size.)
|
|
|
|
The following :const:`!RUSAGE_\*` symbols are passed to the :func:`getrusage`
|
|
function to specify which processes information should be provided for.
|
|
|
|
|
|
.. data:: RUSAGE_SELF
|
|
|
|
Pass to :func:`getrusage` to request resources consumed by the calling
|
|
process, which is the sum of resources used by all threads in the process.
|
|
|
|
|
|
.. data:: RUSAGE_CHILDREN
|
|
|
|
Pass to :func:`getrusage` to request resources consumed by child processes
|
|
of the calling process which have been terminated and waited for.
|
|
|
|
|
|
.. data:: RUSAGE_BOTH
|
|
|
|
Pass to :func:`getrusage` to request resources consumed by both the current
|
|
process and child processes. May not be available on all systems.
|
|
|
|
|
|
.. data:: RUSAGE_THREAD
|
|
|
|
Pass to :func:`getrusage` to request resources consumed by the current
|
|
thread. May not be available on all systems.
|
|
|
|
.. versionadded:: 3.2
|