Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libresource.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents 7f3d0cc21889
children c0d7b5788cbe
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{resource} ---
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
2 Resource usage information}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8018
diff changeset
3
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
4 \declaremodule{builtin}{resource}
10335
093fc298afd6 "\platform{UNIX}" should really be spelled "\platform{Unix}".
Fred Drake <fdrake@acm.org>
parents: 10334
diff changeset
5 \platform{Unix}
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
6 \modulesynopsis{An interface to provide resource usage information on
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
7 the current process.}
20263
873d584c1221 Update a couple of old addresses that point to CNRI.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
8 \moduleauthor{Jeremy Hylton}{jeremy@alum.mit.edu}
873d584c1221 Update a couple of old addresses that point to CNRI.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
9 \sectionauthor{Jeremy Hylton}{jeremy@alum.mit.edu}
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
10
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8018
diff changeset
11
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 This module provides basic mechanisms for measuring and controlling
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 system resources utilized by a program.
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
14
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 Symbolic constants are used to specify particular system resources and
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 to request usage information about either the current process or its
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
17 children.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
18
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
19 A single exception is defined for errors:
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
20
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
21
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
22 \begin{excdesc}{error}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
23 The functions described below may raise this error if the underlying
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
24 system call failures unexpectedly.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
25 \end{excdesc}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
26
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
27 \subsection{Resource Limits}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
28
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
29 Resources usage can be limited using the \function{setrlimit()} function
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 described below. Each resource is controlled by a pair of limits: a
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 soft limit and a hard limit. The soft limit is the current limit, and
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 may be lowered or raised by a process over time. The soft limit can
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 never exceed the hard limit. The hard limit can be lowered to any
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
34 value greater than the soft limit, but not raised. (Only processes with
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
35 the effective UID of the super-user can raise a hard limit.)
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
36
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 The specific resources that can be limited are system dependent. They
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
38 are described in the \manpage{getrlimit}{2} man page. The resources
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
39 listed below are supported when the underlying operating system
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
40 supports them; resources which cannot be checked or controlled by the
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
41 operating system are not defined in this module for those platforms.
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
42
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
43 \begin{funcdesc}{getrlimit}{resource}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
44 Returns a tuple \code{(\var{soft}, \var{hard})} with the current
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
45 soft and hard limits of \var{resource}. Raises \exception{ValueError} if
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
46 an invalid resource is specified, or \exception{error} if the
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
47 underyling system call fails unexpectedly.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
48 \end{funcdesc}
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
49
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
50 \begin{funcdesc}{setrlimit}{resource, limits}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
51 Sets new limits of consumption of \var{resource}. The \var{limits}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
52 argument must be a tuple \code{(\var{soft}, \var{hard})} of two
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
53 integers describing the new limits. A value of \code{-1} can be used to
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
54 specify the maximum possible upper limit.
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
55
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
56 Raises \exception{ValueError} if an invalid resource is specified,
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
57 if the new soft limit exceeds the hard limit, or if a process tries
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
58 to raise its hard limit (unless the process has an effective UID of
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
59 super-user). Can also raise \exception{error} if the underyling
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
60 system call fails.
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
61 \end{funcdesc}
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
62
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
63 These symbols define resources whose consumption can be controlled
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
64 using the \function{setrlimit()} and \function{getrlimit()} functions
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
65 described below. The values of these symbols are exactly the constants
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
66 used by \C{} programs.
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
67
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
68 The \UNIX{} man page for \manpage{getrlimit}{2} lists the available
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
69 resources. Note that not all systems use the same symbol or same
20607
7f3d0cc21889 Clarify that the resource module does not attempt to mask platform
Fred Drake <fdrake@acm.org>
parents: 20263
diff changeset
70 value to denote the same resource. This module does not attempt to
7f3d0cc21889 Clarify that the resource module does not attempt to mask platform
Fred Drake <fdrake@acm.org>
parents: 20263
diff changeset
71 mask platform differences --- symbols not defined for a platform will
7f3d0cc21889 Clarify that the resource module does not attempt to mask platform
Fred Drake <fdrake@acm.org>
parents: 20263
diff changeset
72 not be available from this module on that platform.
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
73
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
74 \begin{datadesc}{RLIMIT_CORE}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
75 The maximum size (in bytes) of a core file that the current process
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
76 can create. This may result in the creation of a partial core file
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
77 if a larger core would be required to contain the entire process
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
78 image.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
79 \end{datadesc}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
80
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
81 \begin{datadesc}{RLIMIT_CPU}
18574
346dcafc878b Minor changes to match the style guide.
Fred Drake <fdrake@acm.org>
parents: 10335
diff changeset
82 The maximum amount of processor time (in seconds) that a process can
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
83 use. If this limit is exceeded, a \constant{SIGXCPU} signal is sent to
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
84 the process. (See the \refmodule{signal} module documentation for
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
85 information about how to catch this signal and do something useful,
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
86 e.g. flush open files to disk.)
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
87 \end{datadesc}
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
88
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
89 \begin{datadesc}{RLIMIT_FSIZE}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
90 The maximum size of a file which the process may create. This only
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
91 affects the stack of the main thread in a multi-threaded process.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
92 \end{datadesc}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
93
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
94 \begin{datadesc}{RLIMIT_DATA}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
95 The maximum size (in bytes) of the process's heap.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
96 \end{datadesc}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
97
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
98 \begin{datadesc}{RLIMIT_STACK}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
99 The maximum size (in bytes) of the call stack for the current
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
100 process.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
101 \end{datadesc}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
102
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
103 \begin{datadesc}{RLIMIT_RSS}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
104 The maximum resident set size that should be made available to the
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
105 process.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
106 \end{datadesc}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
107
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
108 \begin{datadesc}{RLIMIT_NPROC}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
109 The maximum number of processes the current process may create.
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
110 \end{datadesc}
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
111
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
112 \begin{datadesc}{RLIMIT_NOFILE}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
113 The maximum number of open file descriptors for the current
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
114 process.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
115 \end{datadesc}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
116
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
117 \begin{datadesc}{RLIMIT_OFILE}
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
118 The BSD name for \constant{RLIMIT_NOFILE}.
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
119 \end{datadesc}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
120
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
121 \begin{datadesc}{RLIMIT_MEMLOC}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
122 The maximm address space which may be locked in memory.
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
123 \end{datadesc}
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
124
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
125 \begin{datadesc}{RLIMIT_VMEM}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
126 The largest area of mapped memory which the process may occupy.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
127 \end{datadesc}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
128
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
129 \begin{datadesc}{RLIMIT_AS}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
130 The maximum area (in bytes) of address space which may be taken by
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
131 the process.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
132 \end{datadesc}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
133
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
134 \subsection{Resource Usage}
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
135
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
136 These functiona are used to retrieve resource usage information:
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
137
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
138 \begin{funcdesc}{getrusage}{who}
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
139 This function returns a large tuple that describes the resources
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
140 consumed by either the current process or its children, as specified
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
141 by the \var{who} parameter. The \var{who} parameter should be
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
142 specified using one of the \constant{RUSAGE_*} constants described
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
143 below.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
144
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
145 The elements of the return value each
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
146 describe how a particular system resource has been used, e.g. amount
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
147 of time spent running is user mode or number of times the process was
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
148 swapped out of main memory. Some values are dependent on the clock
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
149 tick internal, e.g. the amount of memory the process is using.
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
150
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
151 The first two elements of the return value are floating point values
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
152 representing the amount of time spent executing in user mode and the
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
153 amount of time spent executing in system mode, respectively. The
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
154 remaining values are integers. Consult the \manpage{getrusage}{2}
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
155 man page for detailed information about these values. A brief
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
156 summary is presented here:
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
157
8018
011ae71fea96 Lighten up tables.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
158 \begin{tableii}{r|l}{code}{Offset}{Resource}
6962
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
159 \lineii{0}{time in user mode (float)}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
160 \lineii{1}{time in system mode (float)}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
161 \lineii{2}{maximum resident set size}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
162 \lineii{3}{shared memory size}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
163 \lineii{4}{unshared memory size}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
164 \lineii{5}{unshared stack size}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
165 \lineii{6}{page faults not requiring I/O}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
166 \lineii{7}{page faults requiring I/O}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
167 \lineii{8}{number of swap outs}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
168 \lineii{9}{block input operations}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
169 \lineii{10}{block output operations}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
170 \lineii{11}{messages sent}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
171 \lineii{12}{messages received}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
172 \lineii{13}{signals received}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
173 \lineii{14}{voluntary context switches}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
174 \lineii{15}{involuntary context switches}
484a1c68c558 Use tableii environment for the table instead of tabular. This makes it
Fred Drake <fdrake@acm.org>
parents: 6770
diff changeset
175 \end{tableii}
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
176
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
177 This function will raise a \exception{ValueError} if an invalid
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
178 \var{who} parameter is specified. It may also raise
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
179 \exception{error} exception in unusual circumstances.
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
180 \end{funcdesc}
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
181
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
182 \begin{funcdesc}{getpagesize}{}
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
183 Returns the number of bytes in a system page. (This need not be the
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
184 same as the hardware page size.) This function is useful for
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
185 determining the number of bytes of memory a process is using. The
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
186 third element of the tuple returned by \function{getrusage()} describes
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
187 memory usage in pages; multiplying by page size produces number of
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
188 bytes.
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
189 \end{funcdesc}
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
190
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
191 The following \constant{RUSAGE_*} symbols are passed to the
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
192 \function{getrusage()} function to specify which processes information
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
193 should be provided for.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
194
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
195 \begin{datadesc}{RUSAGE_SELF}
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
196 \constant{RUSAGE_SELF} should be used to
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
197 request information pertaining only to the process itself.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
198 \end{datadesc}
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
199
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
200 \begin{datadesc}{RUSAGE_CHILDREN}
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
201 Pass to \function{getrusage()} to request resource information for
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
202 child processes of the calling process.
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
203 \end{datadesc}
4769
eecbcc48b0e9 Added docs for Jeremy's resource module.
Guido van Rossum <guido@python.org>
parents:
diff changeset
204
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
205 \begin{datadesc}{RUSAGE_BOTH}
7645
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
206 Pass to \function{getrusage()} to request resources consumed by both
7ad522a4c753 Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
207 the current process and child processes. May not be available on all
6770
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
208 systems.
b5cd768812cb Some reorganization (all limit operations & constants together, and all usage
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
209 \end{datadesc}