This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: [doc] resource module documentation is incorrect
Type: behavior Stage: patch review
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: Kurt.Rose, iritkatriel, jrunyon, martin.panter, python-dev, ronaldoussoren, wumpus
Priority: normal Keywords: needs review, patch

Created on 2014-01-31 22:50 by Kurt.Rose, last changed 2022-04-11 14:57 by admin.

File name Uploaded Description Edit
issue-20468.txt ronaldoussoren, 2014-07-23 06:58 review
Messages (8)
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.

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

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:

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

New changeset 1579de0b72f6 by Martin Panter in branch '3.5':
Issue #20468: Merge getpagesize doc from 3.4 into 3.5

New changeset 007dfc0ef1be by Martin Panter in branch 'default':
Issue #20468: Merge getpagesize doc from 3.5

New changeset 58d017d70563 by Martin Panter in branch '2.7':
Issue #20468: Remove incorrect information about maxrss and page size
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.
msg376623 - (view) Author: Greg Lindahl (wumpus) Date: 2020-09-09 08:23
I just tripped on the bug that the maxrss field is kilobytes on Linux and bytes on Darwin.

I don't think referring to the C manpages is sufficient to prevent confusion. I don't actually use my package on a Mac, I just use Travis-CI to test it.
msg407396 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-11-30 18:44
The remaining text is now saying "Returns the number of bytes in a system page". This is still not accurate if it's sometimes number of kilobytes.
Date User Action Args
2022-04-11 14:57:57adminsetgithub: 64667
2021-11-30 18:44:38iritkatrielsetnosy: + iritkatriel
title: resource module documentation is incorrect -> [doc] resource module documentation is incorrect
messages: + msg407396

versions: + Python 3.9, Python 3.10, Python 3.11, - Python 2.7, Python 3.4, Python 3.5, Python 3.6
type: behavior
2020-09-09 08:23:54wumpussetnosy: + wumpus
messages: + msg376623
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