summaryrefslogtreecommitdiff
path: root/sys/src/cmd/python/Doc/lib/libresource.tex
diff options
context:
space:
mode:
authorcinap_lenrek <cinap_lenrek@localhost>2011-05-03 11:25:13 +0000
committercinap_lenrek <cinap_lenrek@localhost>2011-05-03 11:25:13 +0000
commit458120dd40db6b4df55a4e96b650e16798ef06a0 (patch)
tree8f82685be24fef97e715c6f5ca4c68d34d5074ee /sys/src/cmd/python/Doc/lib/libresource.tex
parent3a742c699f6806c1145aea5149bf15de15a0afd7 (diff)
add hg and python
Diffstat (limited to 'sys/src/cmd/python/Doc/lib/libresource.tex')
-rw-r--r--sys/src/cmd/python/Doc/lib/libresource.tex215
1 files changed, 215 insertions, 0 deletions
diff --git a/sys/src/cmd/python/Doc/lib/libresource.tex b/sys/src/cmd/python/Doc/lib/libresource.tex
new file mode 100644
index 000000000..8e102b8ee
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libresource.tex
@@ -0,0 +1,215 @@
+\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}