Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 3c7b2dc

Browse files
gvanrossumgvanrossum
committed
Added docs for Jeremy's resource module.
1 parent 5eaf457 commit 3c7b2dc

5 files changed

Lines changed: 265 additions & 1 deletion

File tree

‎Doc/Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ LIBFILES = lib.tex \
112112
libcd.tex libfl.tex libfm.tex libgl.tex libimgfile.tex libsun.tex \
113113
libxdrlib.tex libimghdr.tex \
114114
librestricted.tex librexec.tex libbastion.tex \
115-
libformatter.tex liboperator.tex libsoundex.tex
115+
libformatter.tex liboperator.tex libsoundex.tex libresource.tex
116116

117117
# Library document
118118
lib.dvi: $(LIBFILES)

‎Doc/lib.tex‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,7 @@
125125
\input{libtermios}
126126
\input{libfcntl}
127127
\input{libposixfile}
128+
\input{libresource}
128129
\input{libsyslog}
129130

130131
\input{libpdb} % The Python Debugger

‎Doc/lib/lib.tex‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,7 @@
125125
\input{libtermios}
126126
\input{libfcntl}
127127
\input{libposixfile}
128+
\input{libresource}
128129
\input{libsyslog}
129130

130131
\input{libpdb} % The Python Debugger

‎Doc/lib/libresource.tex‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
\section{Built-in Module \sectcode{resource}}
2+
3+
\bimodindex{resource}
4+
This module provides basic mechanisms for measuring and controlling
5+
system resources utilized by a program.
6+
7+
Symbolic constants are used to specify particular system resources and
8+
to request usage information about either the current process or its
9+
children.
10+
11+
Resources usage can be limited using the \code{setrlimit} function
12+
described below. Each resource is controlled by a pair of limits: a
13+
soft limit and a hard limit. The soft limit is the current limit, and
14+
may be lowered or raised by a process over time. The soft limit can
15+
never exceed the hard limit. The hard limit can be lowered to any
16+
value greater than the soft limit, but not raised. (Only process with
17+
the effective UID of the super-user can raise a hard limit).
18+
19+
The specific resources that can be limited are system dependent. They
20+
are described in the \code{getrlimit} man page. Typical resources
21+
include:
22+
23+
\begin{description}
24+
25+
\item[RLIMIT_CORE]
26+
The maximum size (in bytes) of a core file that the current process
27+
can create.
28+
29+
\item[RLIMIT_CPU]
30+
The maximum amount of CPU time (in seconds) that a process can use. If
31+
this limit is exceeded, a \code{SIGXCPU} signal is sent to the
32+
process. (See the \code{signal} module documentation for information
33+
about how to catch this signal and do something useful, e.g. flush
34+
open files to disk.)
35+
36+
\end{description}
37+
38+
\begin{datadesc}{RLIMIT_*}
39+
These symbols define resources whose consumption can be controlled
40+
using the \code{setrlimit} and \code{getrlimit} functions defined
41+
below. The values of these symbols are exactly the constants used
42+
by C programs.
43+
44+
The \UNIX{} man page for \file{getrlimit} lists the available
45+
resources. Note that not all systems use the same symbol or same
46+
value to denote the same resource.
47+
\end{datadesc}
48+
49+
\begin{datadesc}{RUSAGE_*}
50+
These symbols are passed to the \code{getrusage} function to specify
51+
whether usage information is being request for the current process,
52+
\code{RUSAGE_SELF} or its child processes \code{RUSAGE_CHILDREN}. On
53+
some system, \code{RUSAGE_BOTH} requests information for both.
54+
\end{datadesc}
55+
56+
\begin{datadesc}{error}
57+
The functions described below may raise this error if the underlying
58+
system call failures unexpectedly.
59+
\end{datadesc}
60+
61+
The resource module defines the following functions:
62+
63+
\begin{funcdesc}{getrusage}{who}
64+
This function returns a large tuple that describes the resources
65+
consumed by either the current process or its children, as specified
66+
by the \var{who} parameter. The elements of the return value each
67+
describe how a particular system resource has been used, e.g. amount
68+
of time spent running is user mode or number of times the process was
69+
swapped out of main memory. Some values are dependent on the clock
70+
tick internal, e.g. the amount of memory the process is using.
71+
72+
The first two elements of the return value are floating point values
73+
representing the amount of time spent executing in user mode and the
74+
amount of time spent executing in system mode, respectively. The
75+
remaining values are integers. Consult the \code{getrusage} man page
76+
for detailed information about these values. A brief summary is
77+
presented here:
78+
79+
\begin{tabular}{rl}
80+
\emph{offset} & \emph{resource} \\
81+
0 & time in user mode (float) \\
82+
1 & time in system mode (float) \\
83+
2 & maximum resident set size \\
84+
3 & shared memory size \\
85+
4 & unshared memory size \\
86+
5 & unshared stack size \\
87+
6 & page faults not requiring I/O \\
88+
7 & page faults requiring I/O \\
89+
8 & number of swap outs \\
90+
9 & block input operations \\
91+
10 & block output operations \\
92+
11 & messages sent \\
93+
12 & messages received \\
94+
13 & signals received \\
95+
14 & voluntary context switches \\
96+
15 & involuntary context switches \\
97+
\end{tabular}
98+
99+
This function will raise a ValueError if an invalid \var{who}
100+
parameter is specified. It may also raise a \code{resource.error}
101+
exception in unusual circumstances.
102+
\end{funcdesc}
103+
104+
\begin{funcdesc}{getpagesize}{}
105+
Returns the number of bytes in a system page. (This need not be the
106+
same as the hardware page size.) This function is useful for
107+
determining the number of bytes of memory a process is using. The
108+
third element of the tuple returned by \code{getrusage} describes
109+
memory usage in pages; multiplying by page size produces number of
110+
bytes.
111+
\end{funcdesc}
112+
113+
\begin{funcdesc}{getrlimit}{resource}
114+
Returns a tuple \code{(\var{soft}, \var{hard})} with the current
115+
soft and hard limits of \var{resource}. Raises ValueError if
116+
an invalid resource is specified, or \code{resource.error} if the
117+
underyling system call fails unexpectedly.
118+
\end{funcdesc}
119+
120+
\begin{funcdesc}{setrlimit}{resource\, limits}
121+
Sets new limits of consumption of \var{resource}. The \var{limits}
122+
argument must be a tuple \code{(\var{soft}, \var{hard})} of two
123+
integers describing the new limits. A value of -1 can be used to
124+
specify the maximum possible upper limit.
125+
126+
Raises ValueError if an invalid resource is specified, if the new
127+
soft limit exceeds the hard limit, or if a process tries to raise its
128+
hard limit (unless the process has an effective UID of
129+
super-user). Can also raise a \code{resource.error} if the
130+
underyling system call fails.
131+
\end{funcdesc}

‎Doc/libresource.tex‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
\section{Built-in Module \sectcode{resource}}
2+
3+
\bimodindex{resource}
4+
This module provides basic mechanisms for measuring and controlling
5+
system resources utilized by a program.
6+
7+
Symbolic constants are used to specify particular system resources and
8+
to request usage information about either the current process or its
9+
children.
10+
11+
Resources usage can be limited using the \code{setrlimit} function
12+
described below. Each resource is controlled by a pair of limits: a
13+
soft limit and a hard limit. The soft limit is the current limit, and
14+
may be lowered or raised by a process over time. The soft limit can
15+
never exceed the hard limit. The hard limit can be lowered to any
16+
value greater than the soft limit, but not raised. (Only process with
17+
the effective UID of the super-user can raise a hard limit).
18+
19+
The specific resources that can be limited are system dependent. They
20+
are described in the \code{getrlimit} man page. Typical resources
21+
include:
22+
23+
\begin{description}
24+
25+
\item[RLIMIT_CORE]
26+
The maximum size (in bytes) of a core file that the current process
27+
can create.
28+
29+
\item[RLIMIT_CPU]
30+
The maximum amount of CPU time (in seconds) that a process can use. If
31+
this limit is exceeded, a \code{SIGXCPU} signal is sent to the
32+
process. (See the \code{signal} module documentation for information
33+
about how to catch this signal and do something useful, e.g. flush
34+
open files to disk.)
35+
36+
\end{description}
37+
38+
\begin{datadesc}{RLIMIT_*}
39+
These symbols define resources whose consumption can be controlled
40+
using the \code{setrlimit} and \code{getrlimit} functions defined
41+
below. The values of these symbols are exactly the constants used
42+
by C programs.
43+
44+
The \UNIX{} man page for \file{getrlimit} lists the available
45+
resources. Note that not all systems use the same symbol or same
46+
value to denote the same resource.
47+
\end{datadesc}
48+
49+
\begin{datadesc}{RUSAGE_*}
50+
These symbols are passed to the \code{getrusage} function to specify
51+
whether usage information is being request for the current process,
52+
\code{RUSAGE_SELF} or its child processes \code{RUSAGE_CHILDREN}. On
53+
some system, \code{RUSAGE_BOTH} requests information for both.
54+
\end{datadesc}
55+
56+
\begin{datadesc}{error}
57+
The functions described below may raise this error if the underlying
58+
system call failures unexpectedly.
59+
\end{datadesc}
60+
61+
The resource module defines the following functions:
62+
63+
\begin{funcdesc}{getrusage}{who}
64+
This function returns a large tuple that describes the resources
65+
consumed by either the current process or its children, as specified
66+
by the \var{who} parameter. The elements of the return value each
67+
describe how a particular system resource has been used, e.g. amount
68+
of time spent running is user mode or number of times the process was
69+
swapped out of main memory. Some values are dependent on the clock
70+
tick internal, e.g. the amount of memory the process is using.
71+
72+
The first two elements of the return value are floating point values
73+
representing the amount of time spent executing in user mode and the
74+
amount of time spent executing in system mode, respectively. The
75+
remaining values are integers. Consult the \code{getrusage} man page
76+
for detailed information about these values. A brief summary is
77+
presented here:
78+
79+
\begin{tabular}{rl}
80+
\emph{offset} & \emph{resource} \\
81+
0 & time in user mode (float) \\
82+
1 & time in system mode (float) \\
83+
2 & maximum resident set size \\
84+
3 & shared memory size \\
85+
4 & unshared memory size \\
86+
5 & unshared stack size \\
87+
6 & page faults not requiring I/O \\
88+
7 & page faults requiring I/O \\
89+
8 & number of swap outs \\
90+
9 & block input operations \\
91+
10 & block output operations \\
92+
11 & messages sent \\
93+
12 & messages received \\
94+
13 & signals received \\
95+
14 & voluntary context switches \\
96+
15 & involuntary context switches \\
97+
\end{tabular}
98+
99+
This function will raise a ValueError if an invalid \var{who}
100+
parameter is specified. It may also raise a \code{resource.error}
101+
exception in unusual circumstances.
102+
\end{funcdesc}
103+
104+
\begin{funcdesc}{getpagesize}{}
105+
Returns the number of bytes in a system page. (This need not be the
106+
same as the hardware page size.) This function is useful for
107+
determining the number of bytes of memory a process is using. The
108+
third element of the tuple returned by \code{getrusage} describes
109+
memory usage in pages; multiplying by page size produces number of
110+
bytes.
111+
\end{funcdesc}
112+
113+
\begin{funcdesc}{getrlimit}{resource}
114+
Returns a tuple \code{(\var{soft}, \var{hard})} with the current
115+
soft and hard limits of \var{resource}. Raises ValueError if
116+
an invalid resource is specified, or \code{resource.error} if the
117+
underyling system call fails unexpectedly.
118+
\end{funcdesc}
119+
120+
\begin{funcdesc}{setrlimit}{resource\, limits}
121+
Sets new limits of consumption of \var{resource}. The \var{limits}
122+
argument must be a tuple \code{(\var{soft}, \var{hard})} of two
123+
integers describing the new limits. A value of -1 can be used to
124+
specify the maximum possible upper limit.
125+
126+
Raises ValueError if an invalid resource is specified, if the new
127+
soft limit exceeds the hard limit, or if a process tries to raise its
128+
hard limit (unless the process has an effective UID of
129+
super-user). Can also raise a \code{resource.error} if the
130+
underyling system call fails.
131+
\end{funcdesc}

0 commit comments

Comments
 (0)