mirror of
https://github.com/python/cpython
synced 2024-10-14 19:05:40 +00:00
Docs: Align multiprocessing.shared_memory docs with Sphinx recommendations (#114103)
- add :class: and :mod: markups where needed - fix incorrect escaping of a star in ShareableList arg spec - mark up parameters with stars: *val* - mark up list of built-in types using list markup - remove unneeded parentheses from :meth: markups
This commit is contained in:
parent
d4dfad2aa9
commit
af85274086
|
@ -20,8 +20,8 @@ and management of shared memory to be accessed by one or more processes
|
|||
on a multicore or symmetric multiprocessor (SMP) machine. To assist with
|
||||
the life-cycle management of shared memory especially across distinct
|
||||
processes, a :class:`~multiprocessing.managers.BaseManager` subclass,
|
||||
:class:`SharedMemoryManager`, is also provided in the
|
||||
``multiprocessing.managers`` module.
|
||||
:class:`~multiprocessing.managers.SharedMemoryManager`, is also provided in the
|
||||
:mod:`multiprocessing.managers` module.
|
||||
|
||||
In this module, shared memory refers to "System V style" shared memory blocks
|
||||
(though is not necessarily implemented explicitly as such) and does not refer
|
||||
|
@ -47,9 +47,9 @@ copying of data.
|
|||
As a resource for sharing data across processes, shared memory blocks
|
||||
may outlive the original process that created them. When one process
|
||||
no longer needs access to a shared memory block that might still be
|
||||
needed by other processes, the :meth:`close()` method should be called.
|
||||
needed by other processes, the :meth:`close` method should be called.
|
||||
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
|
||||
a string. When creating a new shared memory block, if ``None`` (the
|
||||
|
@ -62,7 +62,7 @@ copying of data.
|
|||
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.
|
||||
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.
|
||||
|
@ -86,19 +86,19 @@ copying of data.
|
|||
.. method:: close()
|
||||
|
||||
Closes 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
|
||||
on operating system, the underlying memory may or may not be freed
|
||||
even if all handles to it have been closed. To ensure proper cleanup,
|
||||
use the :meth:`unlink()` method.
|
||||
use the :meth:`unlink` method.
|
||||
|
||||
.. method:: unlink()
|
||||
|
||||
Deletes 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
|
||||
trying to access data inside a shared memory block after :meth:`unlink()`
|
||||
:meth:`unlink` and :meth:`close` can be called in any order, but
|
||||
trying to access data inside a shared memory block after :meth:`unlink`
|
||||
may result in memory access errors, depending on platform.
|
||||
|
||||
This method has no effect on Windows, where the only way to delete a
|
||||
|
@ -145,7 +145,7 @@ instances::
|
|||
|
||||
The following example demonstrates a practical use of the :class:`SharedMemory`
|
||||
class with `NumPy arrays <https://numpy.org/>`_, accessing the
|
||||
same ``numpy.ndarray`` from two distinct Python shells:
|
||||
same :class:`!numpy.ndarray` from two distinct Python shells:
|
||||
|
||||
.. doctest::
|
||||
:options: +SKIP
|
||||
|
@ -197,43 +197,43 @@ same ``numpy.ndarray`` from two distinct Python shells:
|
|||
.. class:: SharedMemoryManager([address[, authkey]])
|
||||
:module: multiprocessing.managers
|
||||
|
||||
A subclass of :class:`~multiprocessing.managers.BaseManager` which can be
|
||||
A subclass of :class:`multiprocessing.managers.BaseManager` which can be
|
||||
used for the management of shared memory blocks across processes.
|
||||
|
||||
A call to :meth:`~multiprocessing.managers.BaseManager.start` on a
|
||||
:class:`SharedMemoryManager` instance causes a new process to be started.
|
||||
:class:`!SharedMemoryManager` instance causes a new process to be started.
|
||||
This new process's sole purpose is to manage the life cycle
|
||||
of all shared memory blocks created through it. To trigger the release
|
||||
of all shared memory blocks managed by that process, call
|
||||
:meth:`~multiprocessing.managers.BaseManager.shutdown()` on the instance.
|
||||
This triggers a :meth:`SharedMemory.unlink()` call on all of the
|
||||
:class:`SharedMemory` objects managed by that process and then
|
||||
stops the process itself. By creating ``SharedMemory`` instances
|
||||
through a ``SharedMemoryManager``, we avoid the need to manually track
|
||||
:meth:`~multiprocessing.managers.BaseManager.shutdown` on the instance.
|
||||
This triggers a :meth:`~multiprocessing.shared_memory.SharedMemory.unlink` call
|
||||
on all of the :class:`SharedMemory` objects managed by that process and then
|
||||
stops the process itself. By creating :class:`!SharedMemory` instances
|
||||
through a :class:`!SharedMemoryManager`, we avoid the need to manually track
|
||||
and trigger the freeing of shared memory resources.
|
||||
|
||||
This class provides methods for creating and returning :class:`SharedMemory`
|
||||
instances and for creating a list-like object (:class:`ShareableList`)
|
||||
backed by shared memory.
|
||||
|
||||
Refer to :class:`multiprocessing.managers.BaseManager` for a description
|
||||
Refer to :class:`~multiprocessing.managers.BaseManager` for a description
|
||||
of the inherited *address* and *authkey* optional input arguments and how
|
||||
they may be used to connect to an existing ``SharedMemoryManager`` service
|
||||
they may be used to connect to an existing :class:`!SharedMemoryManager` service
|
||||
from other processes.
|
||||
|
||||
.. method:: SharedMemory(size)
|
||||
|
||||
Create and return a new :class:`SharedMemory` object with the
|
||||
specified ``size`` in bytes.
|
||||
specified *size* in bytes.
|
||||
|
||||
.. method:: ShareableList(sequence)
|
||||
|
||||
Create and return a new :class:`ShareableList` object, initialized
|
||||
by the values from the input ``sequence``.
|
||||
by the values from the input *sequence*.
|
||||
|
||||
|
||||
The following example demonstrates the basic mechanisms of a
|
||||
:class:`SharedMemoryManager`:
|
||||
:class:`~multiprocessing.managers.SharedMemoryManager`:
|
||||
|
||||
.. doctest::
|
||||
:options: +SKIP
|
||||
|
@ -251,9 +251,9 @@ The following example demonstrates the basic mechanisms of a
|
|||
>>> smm.shutdown() # Calls unlink() on sl, raw_shm, and another_sl
|
||||
|
||||
The following example depicts a potentially more convenient pattern for using
|
||||
:class:`SharedMemoryManager` objects via the :keyword:`with` statement to
|
||||
ensure that all shared memory blocks are released after they are no longer
|
||||
needed:
|
||||
:class:`~multiprocessing.managers.SharedMemoryManager` objects via the
|
||||
:keyword:`with` statement to ensure that all shared memory blocks are released
|
||||
after they are no longer needed:
|
||||
|
||||
.. doctest::
|
||||
:options: +SKIP
|
||||
|
@ -269,38 +269,46 @@ needed:
|
|||
... p2.join() # Wait for all work to complete in both processes
|
||||
... total_result = sum(sl) # Consolidate the partial results now in sl
|
||||
|
||||
When using a :class:`SharedMemoryManager` in a :keyword:`with` statement, the
|
||||
shared memory blocks created using that manager are all released when the
|
||||
:keyword:`with` statement's code block finishes execution.
|
||||
When using a :class:`~multiprocessing.managers.SharedMemoryManager`
|
||||
in a :keyword:`with` statement, the shared memory blocks created using that
|
||||
manager are all released when the :keyword:`!with` statement's code block
|
||||
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
|
||||
stored in a shared memory block. This constrains storable values to
|
||||
only the ``int`` (signed 64-bit), ``float``, ``bool``, ``str`` (less
|
||||
than 10M bytes each when encoded as utf-8), ``bytes`` (less than 10M
|
||||
bytes each), and ``None`` built-in data types. It also notably
|
||||
differs from the built-in ``list`` type in that these lists can not
|
||||
change their overall length (i.e. no append, insert, etc.) and do not
|
||||
support the dynamic creation of new :class:`ShareableList` instances
|
||||
stored in a shared memory block.
|
||||
This constrains storable values to the following built-in data types:
|
||||
|
||||
* :class:`int` (signed 64-bit)
|
||||
* :class:`float`
|
||||
* :class:`bool`
|
||||
* :class:`str` (less than 10M bytes each when encoded as UTF-8)
|
||||
* :class:`bytes` (less than 10M bytes each)
|
||||
* ``None``
|
||||
|
||||
It also notably differs from the built-in :class:`list` type
|
||||
in that these lists can not change their overall length
|
||||
(i.e. no :meth:`!append`, :meth:`!insert`, etc.) and do not
|
||||
support the dynamic creation of new :class:`!ShareableList` instances
|
||||
via slicing.
|
||||
|
||||
*sequence* is used in populating a new ``ShareableList`` full of values.
|
||||
*sequence* is used in populating a new :class:`!ShareableList` full of values.
|
||||
Set to ``None`` to instead attach to an already existing
|
||||
``ShareableList`` by its unique shared memory name.
|
||||
:class:`!ShareableList` by its unique shared memory name.
|
||||
|
||||
*name* is the unique name for the requested shared memory, as described
|
||||
in the definition for :class:`SharedMemory`. When attaching to an
|
||||
existing ``ShareableList``, specify its shared memory block's unique
|
||||
name while leaving ``sequence`` set to ``None``.
|
||||
existing :class:`!ShareableList`, specify its shared memory block's unique
|
||||
name while leaving *sequence* set to ``None``.
|
||||
|
||||
.. note::
|
||||
|
||||
A known issue exists for :class:`bytes` and :class:`str` values.
|
||||
If they end with ``\x00`` nul bytes or characters, those may be
|
||||
*silently stripped* when fetching them by index from the
|
||||
:class:`ShareableList`. This ``.rstrip(b'\x00')`` behavior is
|
||||
:class:`!ShareableList`. This ``.rstrip(b'\x00')`` behavior is
|
||||
considered a bug and may go away in the future. See :gh:`106939`.
|
||||
|
||||
For applications where rstripping of trailing nulls is a problem,
|
||||
|
@ -326,12 +334,12 @@ shared memory blocks created using that manager are all released when the
|
|||
|
||||
.. method:: count(value)
|
||||
|
||||
Returns the number of occurrences of ``value``.
|
||||
Returns the number of occurrences of *value*.
|
||||
|
||||
.. method:: index(value)
|
||||
|
||||
Returns first index position of ``value``. Raises :exc:`ValueError` if
|
||||
``value`` is not present.
|
||||
Returns first index position of *value*. Raises :exc:`ValueError` if
|
||||
*value* is not present.
|
||||
|
||||
.. attribute:: format
|
||||
|
||||
|
@ -391,8 +399,8 @@ behind it:
|
|||
>>> c.shm.close()
|
||||
>>> c.shm.unlink()
|
||||
|
||||
The following examples demonstrates that ``ShareableList``
|
||||
(and underlying ``SharedMemory``) objects
|
||||
The following examples demonstrates that :class:`ShareableList`
|
||||
(and underlying :class:`SharedMemory`) objects
|
||||
can be pickled and unpickled if needed.
|
||||
Note, that it will still be the same shared object.
|
||||
This happens, because the deserialized object has
|
||||
|
|
|
@ -57,7 +57,6 @@ Doc/library/logging.handlers.rst
|
|||
Doc/library/lzma.rst
|
||||
Doc/library/mmap.rst
|
||||
Doc/library/multiprocessing.rst
|
||||
Doc/library/multiprocessing.shared_memory.rst
|
||||
Doc/library/optparse.rst
|
||||
Doc/library/os.rst
|
||||
Doc/library/pickle.rst
|
||||
|
|
Loading…
Reference in a new issue