| \section{Built-in Module \sectcode{resource}} |
| \label{module-resource} |
| |
| \bimodindex{resource} |
| This module provides basic mechanisms for measuring and controlling |
| system resources utilized by a program. |
| |
| Symbolic constants are used to specify particular system resources and |
| to request usage information about either the current process or its |
| children. |
| |
| Resources usage can be limited using the \code{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 process 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 \code{getrlimit} man page. Typical resources |
| include: |
| |
| \begin{description} |
| |
| \item[RLIMIT_CORE] |
| The maximum size (in bytes) of a core file that the current process |
| can create. |
| |
| \item[RLIMIT_CPU] |
| The maximum amount of CPU time (in seconds) that a process can use. If |
| this limit is exceeded, a \code{SIGXCPU} signal is sent to the |
| process. (See the \code{signal} module documentation for information |
| about how to catch this signal and do something useful, e.g. flush |
| open files to disk.) |
| |
| \end{description} |
| |
| \begin{datadesc}{RLIMIT_*} |
| These symbols define resources whose consumption can be controlled |
| using the \code{setrlimit} and \code{getrlimit} functions defined |
| below. The values of these symbols are exactly the constants used |
| by C programs. |
| |
| The \UNIX{} man page for \file{getrlimit} lists the available |
| resources. Note that not all systems use the same symbol or same |
| value to denote the same resource. |
| \end{datadesc} |
| |
| \begin{datadesc}{RUSAGE_*} |
| These symbols are passed to the \code{getrusage} function to specify |
| whether usage information is being request for the current process, |
| \code{RUSAGE_SELF} or its child processes \code{RUSAGE_CHILDREN}. On |
| some system, \code{RUSAGE_BOTH} requests information for both. |
| \end{datadesc} |
| |
| \begin{datadesc}{error} |
| The functions described below may raise this error if the underlying |
| system call failures unexpectedly. |
| \end{datadesc} |
| |
| The resource module defines the following functions: |
| |
| \begin{funcdesc}{getrusage}{who} |
| This function returns a large tuple that describes the resources |
| consumed by either the current process or its children, as specified |
| by the \var{who} parameter. The elements 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. |
| |
| The first two elements 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 \code{getrusage} man page |
| for detailed information about these values. A brief summary is |
| presented here: |
| |
| \begin{tabular}{rl} |
| \emph{offset} & \emph{resource} \\ |
| 0 & time in user mode (float) \\ |
| 1 & time in system mode (float) \\ |
| 2 & maximum resident set size \\ |
| 3 & shared memory size \\ |
| 4 & unshared memory size \\ |
| 5 & unshared stack size \\ |
| 6 & page faults not requiring I/O \\ |
| 7 & page faults requiring I/O \\ |
| 8 & number of swap outs \\ |
| 9 & block input operations \\ |
| 10 & block output operations \\ |
| 11 & messages sent \\ |
| 12 & messages received \\ |
| 13 & signals received \\ |
| 14 & voluntary context switches \\ |
| 15 & involuntary context switches \\ |
| \end{tabular} |
| |
| This function will raise a ValueError if an invalid \var{who} |
| parameter is specified. It may also raise a \code{resource.error} |
| exception in unusual circumstances. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getpagesize}{} |
| Returns the number of bytes in a system page. (This need not be the |
| same as the hardware page size.) This function is useful for |
| determining the number of bytes of memory a process is using. The |
| third element of the tuple returned by \code{getrusage} describes |
| memory usage in pages; multiplying by page size produces number of |
| bytes. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getrlimit}{resource} |
| Returns a tuple \code{(\var{soft}, \var{hard})} with the current |
| soft and hard limits of \var{resource}. Raises ValueError if |
| an invalid resource is specified, or \code{resource.error} if the |
| underyling system call fails unexpectedly. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setrlimit}{resource\, limits} |
| Sets new limits of consumption of \var{resource}. The \var{limits} |
| argument must be a tuple \code{(\var{soft}, \var{hard})} of two |
| integers describing the new limits. A value of -1 can be used to |
| specify the maximum possible upper limit. |
| |
| Raises 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 (unless the process has an effective UID of |
| super-user). Can also raise a \code{resource.error} if the |
| underyling system call fails. |
| \end{funcdesc} |