classification
Title: resource module documentation is incorrect
Type: Stage: patch review
Components: Documentation Versions: Python 3.6, Python 3.4, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: Kurt.Rose, jrunyon, martin.panter, python-dev, ronaldoussoren
Priority: normal Keywords: needs review, patch

Created on 2014-01-31 22:50 by Kurt.Rose, last changed 2015-11-17 22:59 by martin.panter.

Files
File name Uploaded Description Edit
issue-20468.txt ronaldoussoren, 2014-07-23 06:58 review
Messages (6)
msg209844 - (view) Author: Kurt Rose (Kurt.Rose) Date: 2014-01-31 22:50
The documentation in the resource module for get_page_size() is incorrect.

resource.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 getrusage() describes memory usage in pages; multiplying by page size produces number of bytes.

On Linux, the value returned in getrusage().ru_maxrss is in kilobytes.  On OS-X it is in bytes.  Ideally, this could be put into the documentation, but at least remove the inaccurate recommendation to multiply maxrss by page size :-)
msg223727 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2014-07-23 06:58
The attached patch (for the default branch) adds information about the unit of maxrss to the documentation, and removes the sentences about calculating the total memory size from the getpagesize documentation.
msg254796 - (view) Author: John Runyon (jrunyon) * Date: 2015-11-17 11:54
*bump*.

This flat-out wrong documentation has already misled several people, and has had a proposed patch with no comments for over a year.
msg254816 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-11-17 22:07
Python’s getrusage() calls the C-level getrusage() function. Man pages for reference:

http://man7.org/linux/man-pages/man2/getrusage.2.html
https://www.freebsd.org/cgi/man.cgi?query=getrusage&sektion=2
https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man2/getrusage.2.html

I find “kilobytes” ambiguous, since it probably means “kibibytes”, multiples of 1024 bytes, rather than 1000 bytes. Maybe it would be best to just say the unit varies by platform, and let the user check the manuals themself.

I agree about dropping the text from getpagesize() though.
msg254818 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-11-17 22:43
New changeset 5e8b06ac7c97 by Martin Panter in branch '3.4':
Issue #20468: Remove incorrect information about maxrss and page size
https://hg.python.org/cpython/rev/5e8b06ac7c97

New changeset 1579de0b72f6 by Martin Panter in branch '3.5':
Issue #20468: Merge getpagesize doc from 3.4 into 3.5
https://hg.python.org/cpython/rev/1579de0b72f6

New changeset 007dfc0ef1be by Martin Panter in branch 'default':
Issue #20468: Merge getpagesize doc from 3.5
https://hg.python.org/cpython/rev/007dfc0ef1be

New changeset 58d017d70563 by Martin Panter in branch '2.7':
Issue #20468: Remove incorrect information about maxrss and page size
https://hg.python.org/cpython/rev/58d017d70563
msg254819 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-11-17 22:59
I committed the text removal for getpagesize().

For the getrusage() table, I wonder if it is good enough as it already is. Otherwise, it opens questions about the units for all the other fields, and which platforms they are supported on.
History
Date User Action Args
2015-11-17 22:59:46martin.pantersetmessages: + msg254819
versions: + Python 3.6
2015-11-17 22:43:22python-devsetnosy: + python-dev
messages: + msg254818
2015-11-17 22:20:07martin.panterlinkissue24172 superseder
2015-11-17 22:07:01martin.pantersetnosy: + martin.panter
messages: + msg254816
2015-11-17 11:54:16jrunyonsetnosy: + jrunyon
messages: + msg254796
2014-08-29 21:23:54terry.reedysetversions: - Python 3.1, Python 3.2, Python 3.3
2014-07-23 06:58:44ronaldoussorensetfiles: + issue-20468.txt
messages: + msg223727

assignee: ronaldoussoren ->
components: + Documentation, - macOS
keywords: + patch, needs review
stage: patch review
2014-01-31 22:50:41Kurt.Rosecreate