summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libresource.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/lib/libresource.tex')
-rw-r--r--Doc/lib/libresource.tex215
1 files changed, 0 insertions, 215 deletions
diff --git a/Doc/lib/libresource.tex b/Doc/lib/libresource.tex
deleted file mode 100644
index 8e102b8..0000000
--- a/Doc/lib/libresource.tex
+++ /dev/null
@@ -1,215 +0,0 @@
-\section{\module{resource} ---
- Resource usage information}
-
-\declaremodule{builtin}{resource}
- \platform{Unix}
-\modulesynopsis{An interface to provide resource usage information on
- the current process.}
-\moduleauthor{Jeremy Hylton}{jeremy@alum.mit.edu}
-\sectionauthor{Jeremy Hylton}{jeremy@alum.mit.edu}
-
-
-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.
-
-A single exception is defined for errors:
-
-
-\begin{excdesc}{error}
- The functions described below may raise this error if the underlying
- system call failures unexpectedly.
-\end{excdesc}
-
-\subsection{Resource Limits}
-
-Resources usage can be limited using the \function{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 processes 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 \manpage{getrlimit}{2} man page. The resources
-listed below are supported when the underlying operating system
-supports them; resources which cannot be checked or controlled by the
-operating system are not defined in this module for those platforms.
-
-\begin{funcdesc}{getrlimit}{resource}
- Returns a tuple \code{(\var{soft}, \var{hard})} with the current
- soft and hard limits of \var{resource}. Raises \exception{ValueError} if
- an invalid resource is specified, or \exception{error} if the
- underlying 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 \code{-1} can be used to
- specify the maximum possible upper limit.
-
- Raises \exception{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 \exception{error} if the underlying
- system call fails.
-\end{funcdesc}
-
-These symbols define resources whose consumption can be controlled
-using the \function{setrlimit()} and \function{getrlimit()} functions
-described below. The values of these symbols are exactly the constants
-used by \C{} programs.
-
-The \UNIX{} man page for \manpage{getrlimit}{2} lists the available
-resources. Note that not all systems use the same symbol or same
-value to denote the same resource. This module does not attempt to
-mask platform differences --- symbols not defined for a platform will
-not be available from this module on that platform.
-
-\begin{datadesc}{RLIMIT_CORE}
- The maximum size (in bytes) of a core file that the current process
- can create. This may result in the creation of a partial core file
- if a larger core would be required to contain the entire process
- image.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_CPU}
- The maximum amount of processor time (in seconds) that a process can
- use. If this limit is exceeded, a \constant{SIGXCPU} signal is sent to
- the process. (See the \refmodule{signal} module documentation for
- information about how to catch this signal and do something useful,
- e.g. flush open files to disk.)
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_FSIZE}
- The maximum size of a file which the process may create. This only
- affects the stack of the main thread in a multi-threaded process.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_DATA}
- The maximum size (in bytes) of the process's heap.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_STACK}
- The maximum size (in bytes) of the call stack for the current
- process.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_RSS}
- The maximum resident set size that should be made available to the
- process.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_NPROC}
- The maximum number of processes the current process may create.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_NOFILE}
- The maximum number of open file descriptors for the current
- process.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_OFILE}
- The BSD name for \constant{RLIMIT_NOFILE}.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_MEMLOCK}
- The maximum address space which may be locked in memory.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_VMEM}
- The largest area of mapped memory which the process may occupy.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_AS}
- The maximum area (in bytes) of address space which may be taken by
- the process.
-\end{datadesc}
-
-\subsection{Resource Usage}
-
-These functions are used to retrieve resource usage information:
-
-\begin{funcdesc}{getrusage}{who}
- This function returns an object that describes the resources
- consumed by either the current process or its children, as specified
- by the \var{who} parameter. The \var{who} parameter should be
- specified using one of the \constant{RUSAGE_*} constants described
- below.
-
- The fields 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.
-
- For backward compatibility, the return value is also accessible as
- a tuple of 16 elements.
-
- The fields \member{ru_utime} and \member{ru_stime} 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
- \manpage{getrusage}{2} man page for detailed information about these
- values. A brief summary is presented here:
-
-\begin{tableiii}{r|l|l}{code}{Index}{Field}{Resource}
- \lineiii{0}{\member{ru_utime}}{time in user mode (float)}
- \lineiii{1}{\member{ru_stime}}{time in system mode (float)}
- \lineiii{2}{\member{ru_maxrss}}{maximum resident set size}
- \lineiii{3}{\member{ru_ixrss}}{shared memory size}
- \lineiii{4}{\member{ru_idrss}}{unshared memory size}
- \lineiii{5}{\member{ru_isrss}}{unshared stack size}
- \lineiii{6}{\member{ru_minflt}}{page faults not requiring I/O}
- \lineiii{7}{\member{ru_majflt}}{page faults requiring I/O}
- \lineiii{8}{\member{ru_nswap}}{number of swap outs}
- \lineiii{9}{\member{ru_inblock}}{block input operations}
- \lineiii{10}{\member{ru_oublock}}{block output operations}
- \lineiii{11}{\member{ru_msgsnd}}{messages sent}
- \lineiii{12}{\member{ru_msgrcv}}{messages received}
- \lineiii{13}{\member{ru_nsignals}}{signals received}
- \lineiii{14}{\member{ru_nvcsw}}{voluntary context switches}
- \lineiii{15}{\member{ru_nivcsw}}{involuntary context switches}
-\end{tableiii}
-
- This function will raise a \exception{ValueError} if an invalid
- \var{who} parameter is specified. It may also raise
- \exception{error} exception in unusual circumstances.
-
- \versionchanged[Added access to values as attributes of the
- returned object]{2.3}
-\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 \function{getrusage()} describes
- memory usage in pages; multiplying by page size produces number of
- bytes.
-\end{funcdesc}
-
-The following \constant{RUSAGE_*} symbols are passed to the
-\function{getrusage()} function to specify which processes information
-should be provided for.
-
-\begin{datadesc}{RUSAGE_SELF}
- \constant{RUSAGE_SELF} should be used to
- request information pertaining only to the process itself.
-\end{datadesc}
-
-\begin{datadesc}{RUSAGE_CHILDREN}
- Pass to \function{getrusage()} to request resource information for
- child processes of the calling process.
-\end{datadesc}
-
-\begin{datadesc}{RUSAGE_BOTH}
- Pass to \function{getrusage()} to request resources consumed by both
- the current process and child processes. May not be available on all
- systems.
-\end{datadesc}