mirror of
https://github.com/python/cpython.git
synced 2025-12-04 16:43:27 +00:00
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
1 changed files with 42 additions and 34 deletions
|
|
@ -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
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue