Skip to content

Commit 4fdccce

Browse files
committed
gh-151950: Address review feedback for mmap documentation
1 parent eae917d commit 4fdccce

1 file changed

Lines changed: 37 additions & 26 deletions

File tree

‎Doc/library/mmap.rst‎

Lines changed: 37 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -31,26 +31,21 @@ still needs to be closed when done).
3131
that local modifications to the buffers are actually available to the
3232
mapping.
3333

34-
.. data:: ACCESS_DEFAULT
35-
ACCESS_READ
36-
ACCESS_WRITE
37-
ACCESS_COPY
38-
39-
For both the Unix and Windows versions of the constructor, *access* may be
40-
specified as an optional keyword parameter. *access* accepts one of four
41-
values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY`
42-
to specify read-only, write-through or copy-on-write memory respectively,
43-
or :const:`ACCESS_DEFAULT` to defer to *prot*. *access* can be used on both
44-
Unix and Windows. If *access* is not specified, Windows mmap returns a
45-
write-through mapping. The initial memory values for all three access
46-
types are taken from the specified file. Assignment to an
47-
:const:`ACCESS_READ` memory map raises a :exc:`TypeError` exception.
48-
Assignment to an :const:`ACCESS_WRITE` memory map affects both memory and
49-
the underlying file. Assignment to an :const:`ACCESS_COPY` memory map
50-
affects memory but does not update the underlying file.
51-
52-
.. versionchanged:: 3.7
53-
Added :const:`ACCESS_DEFAULT` constant.
34+
For both the Unix and Windows versions of the constructor, *access* may be
35+
specified as an optional keyword parameter. *access* accepts one of four
36+
values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to
37+
specify read-only, write-through or copy-on-write memory respectively, or
38+
:const:`ACCESS_DEFAULT` to defer to *prot*. *access* can be used on both Unix
39+
and Windows. If *access* is not specified, Windows mmap returns a
40+
write-through mapping. The initial memory values for all three access types
41+
are taken from the specified file. Assignment to an :const:`ACCESS_READ`
42+
memory map raises a :exc:`TypeError` exception. Assignment to an
43+
:const:`ACCESS_WRITE` memory map affects both memory and the underlying file.
44+
Assignment to an :const:`ACCESS_COPY` memory map affects memory but does not
45+
update the underlying file.
46+
47+
.. versionchanged:: 3.7
48+
Added :const:`ACCESS_DEFAULT` constant.
5449

5550
To map anonymous memory, -1 should be passed as the fileno along with the length.
5651

@@ -392,9 +387,25 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
392387
the mmap was created with :const:`ACCESS_READ`, then writing to it will
393388
raise a :exc:`TypeError` exception.
394389

390+
.. _access-constants:
391+
392+
ACCESS_* constants
393+
++++++++++++++++++
394+
395+
.. data:: ACCESS_DEFAULT
396+
ACCESS_READ
397+
ACCESS_WRITE
398+
ACCESS_COPY
399+
400+
These constants specify the access mode for a memory mapping.
401+
:const:`ACCESS_READ` provides read-only access, :const:`ACCESS_WRITE`
402+
provides write-through access, and :const:`ACCESS_COPY` provides
403+
copy-on-write access. :const:`ACCESS_DEFAULT` defers to the *prot*
404+
argument of :class:`mmap`.
405+
395406
.. _page-size-constants:
396407

397-
Page Size Constants
408+
Page size constants
398409
+++++++++++++++++++
399410

400411
.. data:: PAGESIZE
@@ -407,7 +418,7 @@ Page Size Constants
407418

408419
.. _prot-constants:
409420

410-
PROT_* Constants
421+
PROT_* constants
411422
++++++++++++++++
412423

413424
.. data:: PROT_READ
@@ -420,11 +431,11 @@ PROT_* Constants
420431
can be combined using the bitwise OR operator. Not every option is present
421432
on every system.
422433

423-
Availability: Unix.
434+
.. availability:: Unix.
424435

425436
.. _madvise-constants:
426437

427-
MADV_* Constants
438+
MADV_* constants
428439
++++++++++++++++
429440

430441
.. data:: MADV_NORMAL
@@ -461,7 +472,7 @@ MADV_* Constants
461472

462473
.. _map-constants:
463474

464-
MAP_* Constants
475+
MAP_* constants
465476
+++++++++++++++
466477

467478
.. data:: MAP_SHARED
@@ -508,7 +519,7 @@ MAP_* Constants
508519

509520
.. _ms-constants:
510521

511-
MS_* Constants
522+
MS_* constants
512523
++++++++++++++
513524

514525
.. data:: MS_SYNC

0 commit comments

Comments
 (0)