Skip to content

Commit 4888db1

Browse files
[3.12] Docs: Align multiprocessing.shared_memory docs with Sphinx recommendations (#114103) (#114112)
(cherry picked from commit af85274) - 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
1 parent 045adb1 commit 4888db1

File tree

2 files changed

+56
-49
lines changed

2 files changed

+56
-49
lines changed

Doc/library/multiprocessing.shared_memory.rst

Lines changed: 56 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,8 @@ and management of shared memory to be accessed by one or more processes
2020
on a multicore or symmetric multiprocessor (SMP) machine. To assist with
2121
the life-cycle management of shared memory especially across distinct
2222
processes, a :class:`~multiprocessing.managers.BaseManager` subclass,
23-
:class:`SharedMemoryManager`, is also provided in the
24-
``multiprocessing.managers`` module.
23+
:class:`~multiprocessing.managers.SharedMemoryManager`, is also provided in the
24+
:mod:`multiprocessing.managers` module.
2525

2626
In this module, shared memory refers to "System V style" shared memory blocks
2727
(though is not necessarily implemented explicitly as such) and does not refer
@@ -47,9 +47,9 @@ copying of data.
4747
As a resource for sharing data across processes, shared memory blocks
4848
may outlive the original process that created them. When one process
4949
no longer needs access to a shared memory block that might still be
50-
needed by other processes, the :meth:`close()` method should be called.
50+
needed by other processes, the :meth:`close` method should be called.
5151
When a shared memory block is no longer needed by any process, the
52-
:meth:`unlink()` method should be called to ensure proper cleanup.
52+
:meth:`unlink` method should be called to ensure proper cleanup.
5353

5454
*name* is the unique name for the requested shared memory, specified as
5555
a string. When creating a new shared memory block, if ``None`` (the
@@ -62,28 +62,28 @@ copying of data.
6262
memory block. Because some platforms choose to allocate chunks of memory
6363
based upon that platform's memory page size, the exact size of the shared
6464
memory block may be larger or equal to the size requested. When attaching
65-
to an existing shared memory block, the ``size`` parameter is ignored.
65+
to an existing shared memory block, the *size* parameter is ignored.
6666

6767
.. method:: close()
6868

6969
Closes access to the shared memory from this instance. In order to
7070
ensure proper cleanup of resources, all instances should call
71-
``close()`` once the instance is no longer needed. Note that calling
72-
``close()`` does not cause the shared memory block itself to be
71+
:meth:`close` once the instance is no longer needed. Note that calling
72+
:meth:`!close` does not cause the shared memory block itself to be
7373
destroyed.
7474

7575
.. method:: unlink()
7676

7777
Requests that the underlying shared memory block be destroyed. In
78-
order to ensure proper cleanup of resources, ``unlink()`` should be
78+
order to ensure proper cleanup of resources, :meth:`unlink` should be
7979
called once (and only once) across all processes which have need
8080
for the shared memory block. After requesting its destruction, a
8181
shared memory block may or may not be immediately destroyed and
8282
this behavior may differ across platforms. Attempts to access data
83-
inside the shared memory block after ``unlink()`` has been called may
83+
inside the shared memory block after :meth:`!unlink` has been called may
8484
result in memory access errors. Note: the last process relinquishing
85-
its hold on a shared memory block may call ``unlink()`` and
86-
:meth:`close()` in either order.
85+
its hold on a shared memory block may call :meth:`!unlink` and
86+
:meth:`close` in either order.
8787

8888
.. attribute:: buf
8989

@@ -126,7 +126,7 @@ instances::
126126

127127
The following example demonstrates a practical use of the :class:`SharedMemory`
128128
class with `NumPy arrays <https://numpy.org/>`_, accessing the
129-
same ``numpy.ndarray`` from two distinct Python shells:
129+
same :class:`!numpy.ndarray` from two distinct Python shells:
130130

131131
.. doctest::
132132
:options: +SKIP
@@ -178,43 +178,43 @@ same ``numpy.ndarray`` from two distinct Python shells:
178178
.. class:: SharedMemoryManager([address[, authkey]])
179179
:module: multiprocessing.managers
180180

181-
A subclass of :class:`~multiprocessing.managers.BaseManager` which can be
181+
A subclass of :class:`multiprocessing.managers.BaseManager` which can be
182182
used for the management of shared memory blocks across processes.
183183

184184
A call to :meth:`~multiprocessing.managers.BaseManager.start` on a
185-
:class:`SharedMemoryManager` instance causes a new process to be started.
185+
:class:`!SharedMemoryManager` instance causes a new process to be started.
186186
This new process's sole purpose is to manage the life cycle
187187
of all shared memory blocks created through it. To trigger the release
188188
of all shared memory blocks managed by that process, call
189-
:meth:`~multiprocessing.managers.BaseManager.shutdown()` on the instance.
190-
This triggers a :meth:`SharedMemory.unlink()` call on all of the
191-
:class:`SharedMemory` objects managed by that process and then
192-
stops the process itself. By creating ``SharedMemory`` instances
193-
through a ``SharedMemoryManager``, we avoid the need to manually track
189+
:meth:`~multiprocessing.managers.BaseManager.shutdown` on the instance.
190+
This triggers a :meth:`~multiprocessing.shared_memory.SharedMemory.unlink` call
191+
on all of the :class:`SharedMemory` objects managed by that process and then
192+
stops the process itself. By creating :class:`!SharedMemory` instances
193+
through a :class:`!SharedMemoryManager`, we avoid the need to manually track
194194
and trigger the freeing of shared memory resources.
195195

196196
This class provides methods for creating and returning :class:`SharedMemory`
197197
instances and for creating a list-like object (:class:`ShareableList`)
198198
backed by shared memory.
199199

200-
Refer to :class:`multiprocessing.managers.BaseManager` for a description
200+
Refer to :class:`~multiprocessing.managers.BaseManager` for a description
201201
of the inherited *address* and *authkey* optional input arguments and how
202-
they may be used to connect to an existing ``SharedMemoryManager`` service
202+
they may be used to connect to an existing :class:`!SharedMemoryManager` service
203203
from other processes.
204204

205205
.. method:: SharedMemory(size)
206206

207207
Create and return a new :class:`SharedMemory` object with the
208-
specified ``size`` in bytes.
208+
specified *size* in bytes.
209209

210210
.. method:: ShareableList(sequence)
211211

212212
Create and return a new :class:`ShareableList` object, initialized
213-
by the values from the input ``sequence``.
213+
by the values from the input *sequence*.
214214

215215

216216
The following example demonstrates the basic mechanisms of a
217-
:class:`SharedMemoryManager`:
217+
:class:`~multiprocessing.managers.SharedMemoryManager`:
218218

219219
.. doctest::
220220
:options: +SKIP
@@ -232,9 +232,9 @@ The following example demonstrates the basic mechanisms of a
232232
>>> smm.shutdown() # Calls unlink() on sl, raw_shm, and another_sl
233233

234234
The following example depicts a potentially more convenient pattern for using
235-
:class:`SharedMemoryManager` objects via the :keyword:`with` statement to
236-
ensure that all shared memory blocks are released after they are no longer
237-
needed:
235+
:class:`~multiprocessing.managers.SharedMemoryManager` objects via the
236+
:keyword:`with` statement to ensure that all shared memory blocks are released
237+
after they are no longer needed:
238238

239239
.. doctest::
240240
:options: +SKIP
@@ -250,38 +250,46 @@ needed:
250250
... p2.join() # Wait for all work to complete in both processes
251251
... total_result = sum(sl) # Consolidate the partial results now in sl
252252

253-
When using a :class:`SharedMemoryManager` in a :keyword:`with` statement, the
254-
shared memory blocks created using that manager are all released when the
255-
:keyword:`with` statement's code block finishes execution.
253+
When using a :class:`~multiprocessing.managers.SharedMemoryManager`
254+
in a :keyword:`with` statement, the shared memory blocks created using that
255+
manager are all released when the :keyword:`!with` statement's code block
256+
finishes execution.
256257

257258

258-
.. class:: ShareableList(sequence=None, \*, name=None)
259+
.. class:: ShareableList(sequence=None, *, name=None)
259260

260261
Provides a mutable list-like object where all values stored within are
261-
stored in a shared memory block. This constrains storable values to
262-
only the ``int`` (signed 64-bit), ``float``, ``bool``, ``str`` (less
263-
than 10M bytes each when encoded as utf-8), ``bytes`` (less than 10M
264-
bytes each), and ``None`` built-in data types. It also notably
265-
differs from the built-in ``list`` type in that these lists can not
266-
change their overall length (i.e. no append, insert, etc.) and do not
267-
support the dynamic creation of new :class:`ShareableList` instances
262+
stored in a shared memory block.
263+
This constrains storable values to the following built-in data types:
264+
265+
* :class:`int` (signed 64-bit)
266+
* :class:`float`
267+
* :class:`bool`
268+
* :class:`str` (less than 10M bytes each when encoded as UTF-8)
269+
* :class:`bytes` (less than 10M bytes each)
270+
* ``None``
271+
272+
It also notably differs from the built-in :class:`list` type
273+
in that these lists can not change their overall length
274+
(i.e. no :meth:`!append`, :meth:`!insert`, etc.) and do not
275+
support the dynamic creation of new :class:`!ShareableList` instances
268276
via slicing.
269277

270-
*sequence* is used in populating a new ``ShareableList`` full of values.
278+
*sequence* is used in populating a new :class:`!ShareableList` full of values.
271279
Set to ``None`` to instead attach to an already existing
272-
``ShareableList`` by its unique shared memory name.
280+
:class:`!ShareableList` by its unique shared memory name.
273281

274282
*name* is the unique name for the requested shared memory, as described
275283
in the definition for :class:`SharedMemory`. When attaching to an
276-
existing ``ShareableList``, specify its shared memory block's unique
277-
name while leaving ``sequence`` set to ``None``.
284+
existing :class:`!ShareableList`, specify its shared memory block's unique
285+
name while leaving *sequence* set to ``None``.
278286

279287
.. note::
280288

281289
A known issue exists for :class:`bytes` and :class:`str` values.
282290
If they end with ``\x00`` nul bytes or characters, those may be
283291
*silently stripped* when fetching them by index from the
284-
:class:`ShareableList`. This ``.rstrip(b'\x00')`` behavior is
292+
:class:`!ShareableList`. This ``.rstrip(b'\x00')`` behavior is
285293
considered a bug and may go away in the future. See :gh:`106939`.
286294

287295
For applications where rstripping of trailing nulls is a problem,
@@ -307,12 +315,12 @@ shared memory blocks created using that manager are all released when the
307315

308316
.. method:: count(value)
309317

310-
Returns the number of occurrences of ``value``.
318+
Returns the number of occurrences of *value*.
311319

312320
.. method:: index(value)
313321

314-
Returns first index position of ``value``. Raises :exc:`ValueError` if
315-
``value`` is not present.
322+
Returns first index position of *value*. Raises :exc:`ValueError` if
323+
*value* is not present.
316324

317325
.. attribute:: format
318326

@@ -372,8 +380,8 @@ behind it:
372380
>>> c.shm.close()
373381
>>> c.shm.unlink()
374382

375-
The following examples demonstrates that ``ShareableList``
376-
(and underlying ``SharedMemory``) objects
383+
The following examples demonstrates that :class:`ShareableList`
384+
(and underlying :class:`SharedMemory`) objects
377385
can be pickled and unpickled if needed.
378386
Note, that it will still be the same shared object.
379387
This happens, because the deserialized object has

Doc/tools/.nitignore

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,6 @@ Doc/library/lzma.rst
6666
Doc/library/mmap.rst
6767
Doc/library/msilib.rst
6868
Doc/library/multiprocessing.rst
69-
Doc/library/multiprocessing.shared_memory.rst
7069
Doc/library/nntplib.rst
7170
Doc/library/optparse.rst
7271
Doc/library/os.rst

0 commit comments

Comments
 (0)