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.

classification
Title: mmap: constants not listed in the documentation
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, goodmami
Priority: normal Keywords: patch

Created on 2021-10-19 19:32 by goodmami, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 29075 open goodmami, 2021-10-19 21:24
Messages (3)
msg404342 - (view) Author: Michael Wayne Goodman (goodmami) * Date: 2021-10-19 19:32
Some constants mentioned in the mmap module documentation are not listed as module contents (i.e., with permalinks), so the mentions do not appear as links and it's not explicit that they are in the mmap module namespace. For instance, ACCESS_READ is referenced but does not link to anything, whereas MAP_PRIVATE links to the MAP_* constants section below showing that it is available as mmap.MAP_PRIVATE.

Constants available but not listed:

* ACCESS_* constants
  - ACCESS_READ
  - ACCESS_WRITE
  - ACCESS_COPY
  - ACCESS_DEFAULT
* PROT_* constants
  - PROT_READ
  - PROT_WRITE
  - PROT_EXEC (this one isn't even mentioned in the docs)
* ALLOCATIONGRANULARITY
* PAGESIZE

These constants are available and unlisted in the documentation for all active versions of Python (except ACCESS_DEFAULT, which is available from 3.7). In addition, none of the MAP_* constants are listed for Python 3.9 and prior, although they all (except MAP_POPULATE) have been available since at least 3.6.

Since these are valid and available constants in the mmap module, can we list them in the documentation for the appropriate versions?
msg404357 - (view) Author: Michael Wayne Goodman (goodmami) * Date: 2021-10-19 21:33
I have added a draft PR on GitHub that adds the lists of constants. As mentioned in the PR, there are a few things that I think could be added before merging:

1. Update descriptions in mmap.mmap, and maybe the intro, to link to relevant sections.

2. Verify the availability of some constants. I only have access to a Unix system, so I cannot easily check if, e.g., the PROT_* constants are unavailable on Windows, or just unused.

3. Provide descriptions for ALLOCATIONGRANULARITY and PAGESIZE. As I understand, allocations occur in chunks at the size of ALLOCATIONGRANULARITY on Windows and PAGESIZE on Unix, although (presumably for portability) mmap.ALLOCATIONGRANULARITY is set to be equal to mmap.PAGESIZE on Unix systems. So does mmap.PAGESIZE have any use on Windows?

I'm not an expert of the low-level implementation of mmap, so I appreciate any help with the above (particularly (2) and (3)).
msg404701 - (view) Author: Michael Wayne Goodman (goodmami) * Date: 2021-10-21 22:53
Also, the first sentences of third paragraph have some problems:

> For both the Unix and Windows versions of the constructor,
> access may be specified as an optional keyword
> parameter. access accepts one of four values: ACCESS_READ,
> ACCESS_WRITE, or ACCESS_COPY to specify read-only,
> write-through or copy-on-write memory respectively, or
> ACCESS_DEFAULT to defer to prot. access can be used on both
> Unix and Windows. If access is not specified, Windows mmap
> returns a write-through mapping.

1. It redundantly says that *access* may be used for Unix and Windows.
2. It says ACCESS_DEFAULT defers to *prot* but doesn't say this is only for Unix nor that *prot* is a parameter.
3. It doesn't say what happens on Unix if *access* is not specified except implicitly by the earlier statement about ACCESS_DEFAULT.

Proposed change:

    For both the Unix and Windows versions of the constructor,
    *access* may be specified as an optional keyword parameter.
    *access* accepts one of the four :ref:`ACCESS_* constants
    <access-constants>`: :const:`ACCESS_READ`,
    :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to specify
    read-only, write-through or copy-on-write memory
    respectively, or :const:`ACCESS_DEFAULT` (the default value
    if *access* is not specified) to return a write-through
    mapping on Windows or defer to the value of the *prot*
    parameter on Unix.
History
Date User Action Args
2022-04-11 14:59:51adminsetgithub: 89691
2021-10-22 07:54:45christian.heimessettype: enhancement
versions: - Python 3.6, Python 3.7, Python 3.8
2021-10-21 22:53:54goodmamisetmessages: + msg404701
2021-10-19 21:33:16goodmamisetmessages: + msg404357
2021-10-19 21:24:19goodmamisetkeywords: + patch
stage: patch review
pull_requests: + pull_request27343
2021-10-19 19:32:50goodmamicreate