Added docs for Jeremy's resource module.

1 files changed, 131 insertions, 0 deletions

diff --git a/Doc/lib/libresource.tex b/Doc/lib/libresource.tex
new file mode 100644
index 0000000..ff78025
--- /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}