diff options
author | cinap_lenrek <cinap_lenrek@localhost> | 2011-05-03 11:25:13 +0000 |
---|---|---|
committer | cinap_lenrek <cinap_lenrek@localhost> | 2011-05-03 11:25:13 +0000 |
commit | 458120dd40db6b4df55a4e96b650e16798ef06a0 (patch) | |
tree | 8f82685be24fef97e715c6f5ca4c68d34d5074ee /sys/src/cmd/python/Doc/lib/libresource.tex | |
parent | 3a742c699f6806c1145aea5149bf15de15a0afd7 (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.tex | 215 |
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} |