diff options
Diffstat (limited to 'Doc/lib/libresource.tex')
-rw-r--r-- | Doc/lib/libresource.tex | 215 |
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} |