Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame^] | 1 | \section{Built-in Module \sectcode{resource}} |
| 2 | |
| 3 | \bimodindex{resource} |
| 4 | This module provides basic mechanisms for measuring and controlling |
| 5 | system resources utilized by a program. |
| 6 | |
| 7 | Symbolic constants are used to specify particular system resources and |
| 8 | to request usage information about either the current process or its |
| 9 | children. |
| 10 | |
| 11 | Resources usage can be limited using the \code{setrlimit} function |
| 12 | described below. Each resource is controlled by a pair of limits: a |
| 13 | soft limit and a hard limit. The soft limit is the current limit, and |
| 14 | may be lowered or raised by a process over time. The soft limit can |
| 15 | never exceed the hard limit. The hard limit can be lowered to any |
| 16 | value greater than the soft limit, but not raised. (Only process with |
| 17 | the effective UID of the super-user can raise a hard limit). |
| 18 | |
| 19 | The specific resources that can be limited are system dependent. They |
| 20 | are described in the \code{getrlimit} man page. Typical resources |
| 21 | include: |
| 22 | |
| 23 | \begin{description} |
| 24 | |
| 25 | \item[RLIMIT_CORE] |
| 26 | The maximum size (in bytes) of a core file that the current process |
| 27 | can create. |
| 28 | |
| 29 | \item[RLIMIT_CPU] |
| 30 | The maximum amount of CPU time (in seconds) that a process can use. If |
| 31 | this limit is exceeded, a \code{SIGXCPU} signal is sent to the |
| 32 | process. (See the \code{signal} module documentation for information |
| 33 | about how to catch this signal and do something useful, e.g. flush |
| 34 | open files to disk.) |
| 35 | |
| 36 | \end{description} |
| 37 | |
| 38 | \begin{datadesc}{RLIMIT_*} |
| 39 | These symbols define resources whose consumption can be controlled |
| 40 | using the \code{setrlimit} and \code{getrlimit} functions defined |
| 41 | below. The values of these symbols are exactly the constants used |
| 42 | by C programs. |
| 43 | |
| 44 | The \UNIX{} man page for \file{getrlimit} lists the available |
| 45 | resources. Note that not all systems use the same symbol or same |
| 46 | value to denote the same resource. |
| 47 | \end{datadesc} |
| 48 | |
| 49 | \begin{datadesc}{RUSAGE_*} |
| 50 | These symbols are passed to the \code{getrusage} function to specify |
| 51 | whether usage information is being request for the current process, |
| 52 | \code{RUSAGE_SELF} or its child processes \code{RUSAGE_CHILDREN}. On |
| 53 | some system, \code{RUSAGE_BOTH} requests information for both. |
| 54 | \end{datadesc} |
| 55 | |
| 56 | \begin{datadesc}{error} |
| 57 | The functions described below may raise this error if the underlying |
| 58 | system call failures unexpectedly. |
| 59 | \end{datadesc} |
| 60 | |
| 61 | The resource module defines the following functions: |
| 62 | |
| 63 | \begin{funcdesc}{getrusage}{who} |
| 64 | This function returns a large tuple that describes the resources |
| 65 | consumed by either the current process or its children, as specified |
| 66 | by the \var{who} parameter. The elements of the return value each |
| 67 | describe how a particular system resource has been used, e.g. amount |
| 68 | of time spent running is user mode or number of times the process was |
| 69 | swapped out of main memory. Some values are dependent on the clock |
| 70 | tick internal, e.g. the amount of memory the process is using. |
| 71 | |
| 72 | The first two elements of the return value are floating point values |
| 73 | representing the amount of time spent executing in user mode and the |
| 74 | amount of time spent executing in system mode, respectively. The |
| 75 | remaining values are integers. Consult the \code{getrusage} man page |
| 76 | for detailed information about these values. A brief summary is |
| 77 | presented here: |
| 78 | |
| 79 | \begin{tabular}{rl} |
| 80 | \emph{offset} & \emph{resource} \\ |
| 81 | 0 & time in user mode (float) \\ |
| 82 | 1 & time in system mode (float) \\ |
| 83 | 2 & maximum resident set size \\ |
| 84 | 3 & shared memory size \\ |
| 85 | 4 & unshared memory size \\ |
| 86 | 5 & unshared stack size \\ |
| 87 | 6 & page faults not requiring I/O \\ |
| 88 | 7 & page faults requiring I/O \\ |
| 89 | 8 & number of swap outs \\ |
| 90 | 9 & block input operations \\ |
| 91 | 10 & block output operations \\ |
| 92 | 11 & messages sent \\ |
| 93 | 12 & messages received \\ |
| 94 | 13 & signals received \\ |
| 95 | 14 & voluntary context switches \\ |
| 96 | 15 & involuntary context switches \\ |
| 97 | \end{tabular} |
| 98 | |
| 99 | This function will raise a ValueError if an invalid \var{who} |
| 100 | parameter is specified. It may also raise a \code{resource.error} |
| 101 | exception in unusual circumstances. |
| 102 | \end{funcdesc} |
| 103 | |
| 104 | \begin{funcdesc}{getpagesize}{} |
| 105 | Returns the number of bytes in a system page. (This need not be the |
| 106 | same as the hardware page size.) This function is useful for |
| 107 | determining the number of bytes of memory a process is using. The |
| 108 | third element of the tuple returned by \code{getrusage} describes |
| 109 | memory usage in pages; multiplying by page size produces number of |
| 110 | bytes. |
| 111 | \end{funcdesc} |
| 112 | |
| 113 | \begin{funcdesc}{getrlimit}{resource} |
| 114 | Returns a tuple \code{(\var{soft}, \var{hard})} with the current |
| 115 | soft and hard limits of \var{resource}. Raises ValueError if |
| 116 | an invalid resource is specified, or \code{resource.error} if the |
| 117 | underyling system call fails unexpectedly. |
| 118 | \end{funcdesc} |
| 119 | |
| 120 | \begin{funcdesc}{setrlimit}{resource\, limits} |
| 121 | Sets new limits of consumption of \var{resource}. The \var{limits} |
| 122 | argument must be a tuple \code{(\var{soft}, \var{hard})} of two |
| 123 | integers describing the new limits. A value of -1 can be used to |
| 124 | specify the maximum possible upper limit. |
| 125 | |
| 126 | Raises ValueError if an invalid resource is specified, if the new |
| 127 | soft limit exceeds the hard limit, or if a process tries to raise its |
| 128 | hard limit (unless the process has an effective UID of |
| 129 | super-user). Can also raise a \code{resource.error} if the |
| 130 | underyling system call fails. |
| 131 | \end{funcdesc} |