bpo-35511: Trivial docs updates for profile and resource library modules. (GH-11124)
polish documentation for profile and resource modules
diff --git a/Doc/library/resource.rst b/Doc/library/resource.rst
index bd49c87..2ed15c1 100644
--- a/Doc/library/resource.rst
+++ b/Doc/library/resource.rst
@@ -261,6 +261,20 @@
*who* parameter should be specified using one of the :const:`RUSAGE_\*`
constants described below.
+ A simple example::
+
+ from resource import *
+ import time
+
+ # a non CPU-bound task
+ time.sleep(3)
+ print(getrusage(RUSAGE_SELF))
+
+ # a CPU-bound task
+ for i in range(10 ** 8):
+ _ = 1 + 1
+ print(getrusage(RUSAGE_SELF))
+
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
@@ -275,41 +289,41 @@
remaining values are integers. Consult the :manpage:`getrusage(2)` man page for
detailed information about these values. A brief summary is presented here:
- +--------+---------------------+-------------------------------+
- | Index | Field | Resource |
- +========+=====================+===============================+
- | ``0`` | :attr:`ru_utime` | time in user mode (float) |
- +--------+---------------------+-------------------------------+
- | ``1`` | :attr:`ru_stime` | time in system mode (float) |
- +--------+---------------------+-------------------------------+
- | ``2`` | :attr:`ru_maxrss` | maximum resident set size |
- +--------+---------------------+-------------------------------+
- | ``3`` | :attr:`ru_ixrss` | shared memory size |
- +--------+---------------------+-------------------------------+
- | ``4`` | :attr:`ru_idrss` | unshared memory size |
- +--------+---------------------+-------------------------------+
- | ``5`` | :attr:`ru_isrss` | unshared stack size |
- +--------+---------------------+-------------------------------+
- | ``6`` | :attr:`ru_minflt` | page faults not requiring I/O |
- +--------+---------------------+-------------------------------+
- | ``7`` | :attr:`ru_majflt` | page faults requiring I/O |
- +--------+---------------------+-------------------------------+
- | ``8`` | :attr:`ru_nswap` | number of swap outs |
- +--------+---------------------+-------------------------------+
- | ``9`` | :attr:`ru_inblock` | block input operations |
- +--------+---------------------+-------------------------------+
- | ``10`` | :attr:`ru_oublock` | block output operations |
- +--------+---------------------+-------------------------------+
- | ``11`` | :attr:`ru_msgsnd` | messages sent |
- +--------+---------------------+-------------------------------+
- | ``12`` | :attr:`ru_msgrcv` | messages received |
- +--------+---------------------+-------------------------------+
- | ``13`` | :attr:`ru_nsignals` | signals received |
- +--------+---------------------+-------------------------------+
- | ``14`` | :attr:`ru_nvcsw` | voluntary context switches |
- +--------+---------------------+-------------------------------+
- | ``15`` | :attr:`ru_nivcsw` | involuntary context switches |
- +--------+---------------------+-------------------------------+
+ +--------+---------------------+---------------------------------------+
+ | Index | Field | Resource |
+ +========+=====================+=======================================+
+ | ``0`` | :attr:`ru_utime` | time in user mode (float seconds) |
+ +--------+---------------------+---------------------------------------+
+ | ``1`` | :attr:`ru_stime` | time in system mode (float seconds) |
+ +--------+---------------------+---------------------------------------+
+ | ``2`` | :attr:`ru_maxrss` | maximum resident set size |
+ +--------+---------------------+---------------------------------------+
+ | ``3`` | :attr:`ru_ixrss` | shared memory size |
+ +--------+---------------------+---------------------------------------+
+ | ``4`` | :attr:`ru_idrss` | unshared memory size |
+ +--------+---------------------+---------------------------------------+
+ | ``5`` | :attr:`ru_isrss` | unshared stack size |
+ +--------+---------------------+---------------------------------------+
+ | ``6`` | :attr:`ru_minflt` | page faults not requiring I/O |
+ +--------+---------------------+---------------------------------------+
+ | ``7`` | :attr:`ru_majflt` | page faults requiring I/O |
+ +--------+---------------------+---------------------------------------+
+ | ``8`` | :attr:`ru_nswap` | number of swap outs |
+ +--------+---------------------+---------------------------------------+
+ | ``9`` | :attr:`ru_inblock` | block input operations |
+ +--------+---------------------+---------------------------------------+
+ | ``10`` | :attr:`ru_oublock` | block output operations |
+ +--------+---------------------+---------------------------------------+
+ | ``11`` | :attr:`ru_msgsnd` | messages sent |
+ +--------+---------------------+---------------------------------------+
+ | ``12`` | :attr:`ru_msgrcv` | messages received |
+ +--------+---------------------+---------------------------------------+
+ | ``13`` | :attr:`ru_nsignals` | signals received |
+ +--------+---------------------+---------------------------------------+
+ | ``14`` | :attr:`ru_nvcsw` | voluntary context switches |
+ +--------+---------------------+---------------------------------------+
+ | ``15`` | :attr:`ru_nivcsw` | involuntary context switches |
+ +--------+---------------------+---------------------------------------+
This function will raise a :exc:`ValueError` if an invalid *who* parameter is
specified. It may also raise :exc:`error` exception in unusual circumstances.