Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{resource}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-resource} |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 3 | |
| 4 | \bimodindex{resource} |
| 5 | This module provides basic mechanisms for measuring and controlling |
| 6 | system resources utilized by a program. |
| 7 | |
| 8 | Symbolic constants are used to specify particular system resources and |
| 9 | to request usage information about either the current process or its |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 10 | children. |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 11 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 12 | A single exception is defined for errors: |
| 13 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame^] | 14 | \setindexsubitem{(in module resource)} |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 15 | |
| 16 | \begin{excdesc}{error} |
| 17 | The functions described below may raise this error if the underlying |
| 18 | system call failures unexpectedly. |
| 19 | \end{excdesc} |
| 20 | |
| 21 | \subsection{Resource Limits} |
| 22 | |
| 23 | Resources usage can be limited using the \code{setrlimit()} function |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 24 | described below. Each resource is controlled by a pair of limits: a |
| 25 | soft limit and a hard limit. The soft limit is the current limit, and |
| 26 | may be lowered or raised by a process over time. The soft limit can |
| 27 | never exceed the hard limit. The hard limit can be lowered to any |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 28 | value greater than the soft limit, but not raised. (Only processes with |
| 29 | the effective UID of the super-user can raise a hard limit.) |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 30 | |
| 31 | The specific resources that can be limited are system dependent. They |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 32 | are described in the \code{getrlimit()} man page. The resources |
| 33 | listed below are supported when the underlying operating system |
| 34 | supports them; resources which cannot be checked or controlled by the |
| 35 | operating system are not defined in this module for those platforms. |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 36 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 37 | \begin{funcdesc}{getrlimit}{resource} |
| 38 | Returns a tuple \code{(\var{soft}, \var{hard})} with the current |
| 39 | soft and hard limits of \var{resource}. Raises \code{ValueError} if |
| 40 | an invalid resource is specified, or \code{resource.error} if the |
| 41 | underyling system call fails unexpectedly. |
| 42 | \end{funcdesc} |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 43 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 44 | \begin{funcdesc}{setrlimit}{resource, limits} |
| 45 | Sets new limits of consumption of \var{resource}. The \var{limits} |
| 46 | argument must be a tuple \code{(\var{soft}, \var{hard})} of two |
| 47 | integers describing the new limits. A value of \code{-1} can be used to |
| 48 | specify the maximum possible upper limit. |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 49 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 50 | Raises \code{ValueError} if an invalid resource is specified, if the new |
| 51 | soft limit exceeds the hard limit, or if a process tries to raise its |
| 52 | hard limit (unless the process has an effective UID of |
| 53 | super-user). Can also raise a \code{resource.error} if the |
| 54 | underyling system call fails. |
| 55 | \end{funcdesc} |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 56 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 57 | These symbols define resources whose consumption can be controlled |
| 58 | using the \code{setrlimit()} and \code{getrlimit()} functions defined |
| 59 | below. The values of these symbols are exactly the constants used |
| 60 | by C programs. |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 61 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 62 | The \UNIX{} man page for \code{getrlimit()} lists the available |
| 63 | resources. Note that not all systems use the same symbol or same |
| 64 | value to denote the same resource. |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 65 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 66 | \begin{datadesc}{RLIMIT_CORE} |
| 67 | The maximum size (in bytes) of a core file that the current process |
| 68 | can create. This may result in the creation of a partial core file |
| 69 | if a larger core would be required to contain the entire process |
| 70 | image. |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 71 | \end{datadesc} |
| 72 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 73 | \begin{datadesc}{RLIMIT_CPU} |
| 74 | The maximum amount of CPU time (in seconds) that a process can |
| 75 | use. If this limit is exceeded, a \code{SIGXCPU} signal is sent to |
| 76 | the process. (See the \code{signal} module documentation for |
| 77 | information about how to catch this signal and do something useful, |
| 78 | e.g. flush open files to disk.) |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 79 | \end{datadesc} |
| 80 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 81 | \begin{datadesc}{RLIMIT_FSIZE} |
| 82 | The maximum size of a file which the process may create. This only |
| 83 | affects the stack of the main thread in a multi-threaded process. |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 84 | \end{datadesc} |
| 85 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 86 | \begin{datadesc}{RLIMIT_DATA} |
| 87 | The maximum size (in bytes) of the process's heap. |
| 88 | \end{datadesc} |
| 89 | |
| 90 | \begin{datadesc}{RLIMIT_STACK} |
| 91 | The maximum size (in bytes) of the call stack for the current |
| 92 | process. |
| 93 | \end{datadesc} |
| 94 | |
| 95 | \begin{datadesc}{RLIMIT_RSS} |
| 96 | The maximum resident set size that should be made available to the |
| 97 | process. |
| 98 | \end{datadesc} |
| 99 | |
| 100 | \begin{datadesc}{RLIMIT_NPROC} |
| 101 | The maximum number of processes the current process may create. |
| 102 | \end{datadesc} |
| 103 | |
| 104 | \begin{datadesc}{RLIMIT_NOFILE} |
| 105 | The maximum number of open file descriptors for the current |
| 106 | process. |
| 107 | \end{datadesc} |
| 108 | |
| 109 | \begin{datadesc}{RLIMIT_OFILE} |
| 110 | The BSD name for \code{RLIMIT_NOFILE}. |
| 111 | \end{datadesc} |
| 112 | |
| 113 | \begin{datadesc}{RLIMIT_MEMLOC} |
| 114 | The maximm address space which may be locked in memory. |
| 115 | \end{datadesc} |
| 116 | |
| 117 | \begin{datadesc}{RLIMIT_VMEM} |
| 118 | The largest area of mapped memory which the process may occupy. |
| 119 | \end{datadesc} |
| 120 | |
| 121 | \begin{datadesc}{RLIMIT_AS} |
| 122 | The maximum area (in bytes) of address space which may be taken by |
| 123 | the process. |
| 124 | \end{datadesc} |
| 125 | |
| 126 | \subsection{Resource Usage} |
| 127 | |
| 128 | These functiona are used to retrieve resource usage information: |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 129 | |
| 130 | \begin{funcdesc}{getrusage}{who} |
| 131 | This function returns a large tuple that describes the resources |
| 132 | consumed by either the current process or its children, as specified |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 133 | by the \var{who} parameter. The \var{who} parameter should be |
| 134 | specified using one of the \code{RUSAGE_}* constants described |
| 135 | below. |
| 136 | |
| 137 | The elements of the return value each |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 138 | describe how a particular system resource has been used, e.g. amount |
| 139 | of time spent running is user mode or number of times the process was |
| 140 | swapped out of main memory. Some values are dependent on the clock |
| 141 | tick internal, e.g. the amount of memory the process is using. |
| 142 | |
| 143 | The first two elements of the return value are floating point values |
| 144 | representing the amount of time spent executing in user mode and the |
| 145 | amount of time spent executing in system mode, respectively. The |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 146 | remaining values are integers. Consult the \code{getrusage()} man page |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 147 | for detailed information about these values. A brief summary is |
| 148 | presented here: |
| 149 | |
Fred Drake | c416445 | 1997-12-29 19:02:01 +0000 | [diff] [blame] | 150 | \begin{tableii}{|r|l|}{code}{Offset}{Resource} |
| 151 | \lineii{0}{time in user mode (float)} |
| 152 | \lineii{1}{time in system mode (float)} |
| 153 | \lineii{2}{maximum resident set size} |
| 154 | \lineii{3}{shared memory size} |
| 155 | \lineii{4}{unshared memory size} |
| 156 | \lineii{5}{unshared stack size} |
| 157 | \lineii{6}{page faults not requiring I/O} |
| 158 | \lineii{7}{page faults requiring I/O} |
| 159 | \lineii{8}{number of swap outs} |
| 160 | \lineii{9}{block input operations} |
| 161 | \lineii{10}{block output operations} |
| 162 | \lineii{11}{messages sent} |
| 163 | \lineii{12}{messages received} |
| 164 | \lineii{13}{signals received} |
| 165 | \lineii{14}{voluntary context switches} |
| 166 | \lineii{15}{involuntary context switches} |
| 167 | \end{tableii} |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 168 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 169 | This function will raise a \code{ValueError} if an invalid \var{who} |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 170 | parameter is specified. It may also raise a \code{resource.error} |
| 171 | exception in unusual circumstances. |
| 172 | \end{funcdesc} |
| 173 | |
| 174 | \begin{funcdesc}{getpagesize}{} |
| 175 | Returns the number of bytes in a system page. (This need not be the |
| 176 | same as the hardware page size.) This function is useful for |
| 177 | determining the number of bytes of memory a process is using. The |
| 178 | third element of the tuple returned by \code{getrusage} describes |
| 179 | memory usage in pages; multiplying by page size produces number of |
| 180 | bytes. |
| 181 | \end{funcdesc} |
| 182 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 183 | The following \code{RUSAGE_}* symbols are passed to the |
| 184 | \code{getrusage()} function to specify which processes information |
| 185 | should be provided for. |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 186 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 187 | \begin{datadesc}{RUSAGE_SELF} |
| 188 | \code{RUSAGE_SELF} should be used to |
| 189 | request information pertaining only to the process itself. |
| 190 | \end{datadesc} |
Guido van Rossum | 3c7b2dc | 1996-12-18 18:37:05 +0000 | [diff] [blame] | 191 | |
Fred Drake | e907208 | 1997-12-06 07:25:41 +0000 | [diff] [blame] | 192 | \begin{datadesc}{RUSAGE_CHILDREN} |
| 193 | Pass to \code{getrusage()} to request resource information for child |
| 194 | processes of the calling process. |
| 195 | \end{datadesc} |
| 196 | |
| 197 | \begin{datadesc}{RUSAGE_BOTH} |
| 198 | Pass to \code{getrusage()} to request resources consumed by both the |
| 199 | current process and child processes. May not be available on all |
| 200 | systems. |
| 201 | \end{datadesc} |