Docs: Improve multiprocessing.SharedMemory reference (#114093)

Align the multiprocessing shared memory docs with Diatáxis's
recommendations for references.

- use a parameter list for the SharedMemory.__init__() argument spec
- use the imperative mode
- use versionadded, not versionchanged, for added parameters
- reflow touched lines according to SemBr
This commit is contained in:
Erlend E. Aasland 2024-01-16 17:43:13 +01:00 committed by GitHub
parent de4ced54eb
commit b1db6278cf
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -38,7 +38,8 @@ copying of data.
.. class:: SharedMemory(name=None, create=False, size=0, *, track=True) .. class:: SharedMemory(name=None, create=False, size=0, *, track=True)
Creates a new shared memory block or attaches to an existing shared Create an instance of the :class:`!SharedMemory` class for either
creating a new shared memory block or attaching to an existing shared
memory block. Each shared memory block is assigned a unique name. memory block. Each shared memory block is assigned a unique name.
In this way, one process can create a shared memory block with a In this way, one process can create a shared memory block with a
particular name and a different process can attach to that same shared particular name and a different process can attach to that same shared
@ -51,20 +52,26 @@ copying of data.
When a shared memory block is no longer needed by any process, the When a shared memory block is no longer needed by any process, the
:meth:`unlink` method should be called to ensure proper cleanup. :meth:`unlink` method should be called to ensure proper cleanup.
*name* is the unique name for the requested shared memory, specified as :param name:
a string. When creating a new shared memory block, if ``None`` (the The unique name for the requested shared memory, specified as a string.
default) is supplied for the name, a novel name will be generated. When creating a new shared memory block, if ``None`` (the default)
is supplied for the name, a novel name will be generated.
:type name: str | None
*create* controls whether a new shared memory block is created (``True``) :param bool create:
Control whether a new shared memory block is created (``True``)
or an existing shared memory block is attached (``False``). or an existing shared memory block is attached (``False``).
*size* specifies the requested number of bytes when creating a new shared :param int size:
memory block. Because some platforms choose to allocate chunks of memory The requested number of bytes when creating a new shared memory block.
Because some platforms choose to allocate chunks of memory
based upon that platform's memory page size, the exact size of the shared based upon that platform's memory page size, the exact size of the shared
memory block may be larger or equal to the size requested. When attaching memory block may be larger or equal to the size requested.
to an existing shared memory block, the *size* parameter is ignored. When attaching to an existing shared memory block,
the *size* parameter is ignored.
*track*, when enabled, registers the shared memory block with a resource :param bool track:
When ``True``, register the shared memory block with a resource
tracker process on platforms where the OS does not do this automatically. tracker process on platforms where the OS does not do this automatically.
The resource tracker ensures proper cleanup of the shared memory even The resource tracker ensures proper cleanup of the shared memory even
if all other processes with access to the memory exit without doing so. if all other processes with access to the memory exit without doing so.
@ -81,11 +88,12 @@ copying of data.
*track* is ignored on Windows, which has its own tracking and *track* is ignored on Windows, which has its own tracking and
automatically deletes shared memory when all handles to it have been closed. automatically deletes shared memory when all handles to it have been closed.
.. versionchanged:: 3.13 Added *track* parameter. .. versionadded:: 3.13
The *track* parameter.
.. method:: close() .. method:: close()
Closes the file descriptor/handle to the shared memory from this Close the file descriptor/handle to the shared memory from this
instance. :meth:`close` should be called once access to the shared instance. :meth:`close` should be called once access to the shared
memory block from this instance is no longer needed. Depending memory block from this instance is no longer needed. Depending
on operating system, the underlying memory may or may not be freed on operating system, the underlying memory may or may not be freed
@ -94,7 +102,7 @@ copying of data.
.. method:: unlink() .. method:: unlink()
Deletes the underlying shared memory block. This should be called only Delete the underlying shared memory block. This should be called only
once per shared memory block regardless of the number of handles to it, once per shared memory block regardless of the number of handles to it,
even in other processes. even in other processes.
:meth:`unlink` and :meth:`close` can be called in any order, but :meth:`unlink` and :meth:`close` can be called in any order, but
@ -277,7 +285,7 @@ finishes execution.
.. class:: ShareableList(sequence=None, *, name=None) .. class:: ShareableList(sequence=None, *, name=None)
Provides a mutable list-like object where all values stored within are Provide a mutable list-like object where all values stored within are
stored in a shared memory block. stored in a shared memory block.
This constrains storable values to the following built-in data types: This constrains storable values to the following built-in data types:
@ -334,12 +342,12 @@ finishes execution.
.. method:: count(value) .. method:: count(value)
Returns the number of occurrences of *value*. Return the number of occurrences of *value*.
.. method:: index(value) .. method:: index(value)
Returns first index position of *value*. Raises :exc:`ValueError` if Return first index position of *value*.
*value* is not present. Raise :exc:`ValueError` if *value* is not present.
.. attribute:: format .. attribute:: format