Home | History | Annotate | Download | only in library
      1 
      2 :mod:`resource` --- Resource usage information
      3 ==============================================
      4 
      5 .. module:: resource
      6    :platform: Unix
      7    :synopsis: An interface to provide resource usage information on the current process.
      8 .. moduleauthor:: Jeremy Hylton <jeremy (a] alum.mit.edu>
      9 .. sectionauthor:: Jeremy Hylton <jeremy (a] alum.mit.edu>
     10 
     11 
     12 This module provides basic mechanisms for measuring and controlling system
     13 resources utilized by a program.
     14 
     15 Symbolic constants are used to specify particular system resources and to
     16 request usage information about either the current process or its children.
     17 
     18 A single exception is defined for errors:
     19 
     20 
     21 .. exception:: error
     22 
     23    The functions described below may raise this error if the underlying system call
     24    failures unexpectedly.
     25 
     26 
     27 Resource Limits
     28 ---------------
     29 
     30 Resources usage can be limited using the :func:`setrlimit` function described
     31 below. Each resource is controlled by a pair of limits: a soft limit and a hard
     32 limit. The soft limit is the current limit, and may be lowered or raised by a
     33 process over time. The soft limit can never exceed the hard limit. The hard
     34 limit can be lowered to any value greater than the soft limit, but not raised.
     35 (Only processes with the effective UID of the super-user can raise a hard
     36 limit.)
     37 
     38 The specific resources that can be limited are system dependent. They are
     39 described in the :manpage:`getrlimit(2)` man page.  The resources listed below
     40 are supported when the underlying operating system supports them; resources
     41 which cannot be checked or controlled by the operating system are not defined in
     42 this module for those platforms.
     43 
     44 
     45 .. data:: RLIM_INFINITY
     46 
     47    Constant used to represent the limit for an unlimited resource.
     48 
     49 
     50 .. function:: getrlimit(resource)
     51 
     52    Returns a tuple ``(soft, hard)`` with the current soft and hard limits of
     53    *resource*. Raises :exc:`ValueError` if an invalid resource is specified, or
     54    :exc:`error` if the underlying system call fails unexpectedly.
     55 
     56 
     57 .. function:: setrlimit(resource, limits)
     58 
     59    Sets new limits of consumption of *resource*. The *limits* argument must be a
     60    tuple ``(soft, hard)`` of two integers describing the new limits. A value of
     61    :data:`~resource.RLIM_INFINITY` can be used to request a limit that is
     62    unlimited.
     63 
     64    Raises :exc:`ValueError` if an invalid resource is specified, if the new soft
     65    limit exceeds the hard limit, or if a process tries to raise its hard limit.
     66    Specifying a limit of :data:`~resource.RLIM_INFINITY` when the hard or
     67    system limit for that resource is not unlimited will result in a
     68    :exc:`ValueError`.  A process with the effective UID of super-user can
     69    request any valid limit value, including unlimited, but :exc:`ValueError`
     70    will still be raised if the requested limit exceeds the system imposed
     71    limit.
     72 
     73    ``setrlimit`` may also raise :exc:`error` if the underlying system call
     74    fails.
     75 
     76 These symbols define resources whose consumption can be controlled using the
     77 :func:`setrlimit` and :func:`getrlimit` functions described below. The values of
     78 these symbols are exactly the constants used by C programs.
     79 
     80 The Unix man page for :manpage:`getrlimit(2)` lists the available resources.
     81 Note that not all systems use the same symbol or same value to denote the same
     82 resource.  This module does not attempt to mask platform differences --- symbols
     83 not defined for a platform will not be available from this module on that
     84 platform.
     85 
     86 
     87 .. data:: RLIMIT_CORE
     88 
     89    The maximum size (in bytes) of a core file that the current process can create.
     90    This may result in the creation of a partial core file if a larger core would be
     91    required to contain the entire process image.
     92 
     93 
     94 .. data:: RLIMIT_CPU
     95 
     96    The maximum amount of processor time (in seconds) that a process can use. If
     97    this limit is exceeded, a :const:`SIGXCPU` signal is sent to the process. (See
     98    the :mod:`signal` module documentation for information about how to catch this
     99    signal and do something useful, e.g. flush open files to disk.)
    100 
    101 
    102 .. data:: RLIMIT_FSIZE
    103 
    104    The maximum size of a file which the process may create.
    105 
    106 
    107 .. data:: RLIMIT_DATA
    108 
    109    The maximum size (in bytes) of the process's heap.
    110 
    111 
    112 .. data:: RLIMIT_STACK
    113 
    114    The maximum size (in bytes) of the call stack for the current process.  This only
    115    affects the stack of the main thread in a multi-threaded process.
    116 
    117 
    118 .. data:: RLIMIT_RSS
    119 
    120    The maximum resident set size that should be made available to the process.
    121 
    122 
    123 .. data:: RLIMIT_NPROC
    124 
    125    The maximum number of processes the current process may create.
    126 
    127 
    128 .. data:: RLIMIT_NOFILE
    129 
    130    The maximum number of open file descriptors for the current process.
    131 
    132 
    133 .. data:: RLIMIT_OFILE
    134 
    135    The BSD name for :const:`RLIMIT_NOFILE`.
    136 
    137 
    138 .. data:: RLIMIT_MEMLOCK
    139 
    140    The maximum address space which may be locked in memory.
    141 
    142 
    143 .. data:: RLIMIT_VMEM
    144 
    145    The largest area of mapped memory which the process may occupy.
    146 
    147 
    148 .. data:: RLIMIT_AS
    149 
    150    The maximum area (in bytes) of address space which may be taken by the process.
    151 
    152 
    153 Resource Usage
    154 --------------
    155 
    156 These functions are used to retrieve resource usage information:
    157 
    158 
    159 .. function:: getrusage(who)
    160 
    161    This function returns an object that describes the resources consumed by either
    162    the current process or its children, as specified by the *who* parameter.  The
    163    *who* parameter should be specified using one of the :const:`RUSAGE_\*`
    164    constants described below.
    165 
    166    The fields of the return value each describe how a particular system resource
    167    has been used, e.g. amount of time spent running is user mode or number of times
    168    the process was swapped out of main memory. Some values are dependent on the
    169    clock tick internal, e.g. the amount of memory the process is using.
    170 
    171    For backward compatibility, the return value is also accessible as a tuple of 16
    172    elements.
    173 
    174    The fields :attr:`ru_utime` and :attr:`ru_stime` of the return value are
    175    floating point values representing the amount of time spent executing in user
    176    mode and the amount of time spent executing in system mode, respectively. The
    177    remaining values are integers. Consult the :manpage:`getrusage(2)` man page for
    178    detailed information about these values. A brief summary is presented here:
    179 
    180    +--------+---------------------+-------------------------------+
    181    | Index  | Field               | Resource                      |
    182    +========+=====================+===============================+
    183    | ``0``  | :attr:`ru_utime`    | time in user mode (float)     |
    184    +--------+---------------------+-------------------------------+
    185    | ``1``  | :attr:`ru_stime`    | time in system mode (float)   |
    186    +--------+---------------------+-------------------------------+
    187    | ``2``  | :attr:`ru_maxrss`   | maximum resident set size     |
    188    +--------+---------------------+-------------------------------+
    189    | ``3``  | :attr:`ru_ixrss`    | shared memory size            |
    190    +--------+---------------------+-------------------------------+
    191    | ``4``  | :attr:`ru_idrss`    | unshared memory size          |
    192    +--------+---------------------+-------------------------------+
    193    | ``5``  | :attr:`ru_isrss`    | unshared stack size           |
    194    +--------+---------------------+-------------------------------+
    195    | ``6``  | :attr:`ru_minflt`   | page faults not requiring I/O |
    196    +--------+---------------------+-------------------------------+
    197    | ``7``  | :attr:`ru_majflt`   | page faults requiring I/O     |
    198    +--------+---------------------+-------------------------------+
    199    | ``8``  | :attr:`ru_nswap`    | number of swap outs           |
    200    +--------+---------------------+-------------------------------+
    201    | ``9``  | :attr:`ru_inblock`  | block input operations        |
    202    +--------+---------------------+-------------------------------+
    203    | ``10`` | :attr:`ru_oublock`  | block output operations       |
    204    +--------+---------------------+-------------------------------+
    205    | ``11`` | :attr:`ru_msgsnd`   | messages sent                 |
    206    +--------+---------------------+-------------------------------+
    207    | ``12`` | :attr:`ru_msgrcv`   | messages received             |
    208    +--------+---------------------+-------------------------------+
    209    | ``13`` | :attr:`ru_nsignals` | signals received              |
    210    +--------+---------------------+-------------------------------+
    211    | ``14`` | :attr:`ru_nvcsw`    | voluntary context switches    |
    212    +--------+---------------------+-------------------------------+
    213    | ``15`` | :attr:`ru_nivcsw`   | involuntary context switches  |
    214    +--------+---------------------+-------------------------------+
    215 
    216    This function will raise a :exc:`ValueError` if an invalid *who* parameter is
    217    specified. It may also raise :exc:`error` exception in unusual circumstances.
    218 
    219    .. versionchanged:: 2.3
    220       Added access to values as attributes of the returned object.
    221 
    222 
    223 .. function:: getpagesize()
    224 
    225    Returns the number of bytes in a system page. (This need not be the same as the
    226    hardware page size.)
    227 
    228 The following :const:`RUSAGE_\*` symbols are passed to the :func:`getrusage`
    229 function to specify which processes information should be provided for.
    230 
    231 
    232 .. data:: RUSAGE_SELF
    233 
    234    :const:`RUSAGE_SELF` should be used to request information pertaining only to
    235    the process itself.
    236 
    237 
    238 .. data:: RUSAGE_CHILDREN
    239 
    240    Pass to :func:`getrusage` to request resource information for child processes of
    241    the calling process.
    242 
    243 
    244 .. data:: RUSAGE_BOTH
    245 
    246    Pass to :func:`getrusage` to request resources consumed by both the current
    247    process and child processes.  May not be available on all systems.
    248 
    249