133 lines
5.2 KiB
TeX
133 lines
5.2 KiB
TeX
\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}
|