diff options
Diffstat (limited to 'Doc/lib')
| -rw-r--r-- | Doc/lib/lib.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/libresource.tex | 131 |
2 files changed, 132 insertions, 0 deletions
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index c6d203d599..db027a9bae 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -125,6 +125,7 @@ to Python and how to embed it in other applications. \input{libtermios} \input{libfcntl} \input{libposixfile} +\input{libresource} \input{libsyslog} \input{libpdb} % The Python Debugger diff --git a/Doc/lib/libresource.tex b/Doc/lib/libresource.tex new file mode 100644 index 0000000000..ff78025ca3 --- /dev/null +++ b/Doc/lib/libresource.tex @@ -0,0 +1,131 @@ +\section{Built-in Module \sectcode{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} |