mirror of https://github.com/python/cpython
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:
parent
de4ced54eb
commit
b1db6278cf
|
@ -38,7 +38,8 @@ copying of data.
|
|||
|
||||
.. 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.
|
||||
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
|
||||
|
@ -51,41 +52,48 @@ copying of data.
|
|||
When a shared memory block is no longer needed by any process, the
|
||||
:meth:`unlink` method should be called to ensure proper cleanup.
|
||||
|
||||
*name* is the unique name for the requested shared memory, specified as
|
||||
a string. When creating a new shared memory block, if ``None`` (the
|
||||
default) is supplied for the name, a novel name will be generated.
|
||||
:param name:
|
||||
The unique name for the requested shared memory, specified as a string.
|
||||
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``)
|
||||
or an existing shared memory block is attached (``False``).
|
||||
:param bool create:
|
||||
Control whether a new shared memory block is created (``True``)
|
||||
or an existing shared memory block is attached (``False``).
|
||||
|
||||
*size* specifies 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
|
||||
memory block may be larger or equal to the size requested. When attaching
|
||||
to an existing shared memory block, the *size* parameter is ignored.
|
||||
:param int size:
|
||||
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
|
||||
memory block may be larger or equal to the size requested.
|
||||
When attaching to an existing shared memory block,
|
||||
the *size* parameter is ignored.
|
||||
|
||||
*track*, when enabled, registers the shared memory block with a resource
|
||||
tracker process on platforms where the OS does not do this automatically.
|
||||
The resource tracker ensures proper cleanup of the shared memory even
|
||||
if all other processes with access to the memory exit without doing so.
|
||||
Python processes created from a common ancestor using :mod:`multiprocessing`
|
||||
facilities share a single resource tracker process, and the lifetime of
|
||||
shared memory segments is handled automatically among these processes.
|
||||
Python processes created in any other way will receive their own
|
||||
resource tracker when accessing shared memory with *track* enabled.
|
||||
This will cause the shared memory to be deleted by the resource tracker
|
||||
of the first process that terminates.
|
||||
To avoid this issue, users of :mod:`subprocess` or standalone Python
|
||||
processes should set *track* to ``False`` when there is already another
|
||||
process in place that does the bookkeeping.
|
||||
*track* is ignored on Windows, which has its own tracking and
|
||||
automatically deletes shared memory when all handles to it have been closed.
|
||||
: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.
|
||||
The resource tracker ensures proper cleanup of the shared memory even
|
||||
if all other processes with access to the memory exit without doing so.
|
||||
Python processes created from a common ancestor using :mod:`multiprocessing`
|
||||
facilities share a single resource tracker process, and the lifetime of
|
||||
shared memory segments is handled automatically among these processes.
|
||||
Python processes created in any other way will receive their own
|
||||
resource tracker when accessing shared memory with *track* enabled.
|
||||
This will cause the shared memory to be deleted by the resource tracker
|
||||
of the first process that terminates.
|
||||
To avoid this issue, users of :mod:`subprocess` or standalone Python
|
||||
processes should set *track* to ``False`` when there is already another
|
||||
process in place that does the bookkeeping.
|
||||
*track* is ignored on Windows, which has its own tracking and
|
||||
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()
|
||||
|
||||
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
|
||||
memory block from this instance is no longer needed. Depending
|
||||
on operating system, the underlying memory may or may not be freed
|
||||
|
@ -94,7 +102,7 @@ copying of data.
|
|||
|
||||
.. 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,
|
||||
even in other processes.
|
||||
:meth:`unlink` and :meth:`close` can be called in any order, but
|
||||
|
@ -277,7 +285,7 @@ finishes execution.
|
|||
|
||||
.. 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.
|
||||
This constrains storable values to the following built-in data types:
|
||||
|
||||
|
@ -334,12 +342,12 @@ finishes execution.
|
|||
|
||||
.. method:: count(value)
|
||||
|
||||
Returns the number of occurrences of *value*.
|
||||
Return the number of occurrences of *value*.
|
||||
|
||||
.. method:: index(value)
|
||||
|
||||
Returns first index position of *value*. Raises :exc:`ValueError` if
|
||||
*value* is not present.
|
||||
Return first index position of *value*.
|
||||
Raise :exc:`ValueError` if *value* is not present.
|
||||
|
||||
.. attribute:: format
|
||||
|
||||
|
|
Loading…
Reference in New Issue