@@ -20,8 +20,8 @@ and management of shared memory to be accessed by one or more processes
20
20
on a multicore or symmetric multiprocessor (SMP) machine. To assist with
21
21
the life-cycle management of shared memory especially across distinct
22
22
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.
25
25
26
26
In this module, shared memory refers to "System V style" shared memory blocks
27
27
(though is not necessarily implemented explicitly as such) and does not refer
@@ -47,9 +47,9 @@ copying of data.
47
47
As a resource for sharing data across processes, shared memory blocks
48
48
may outlive the original process that created them. When one process
49
49
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.
51
51
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.
53
53
54
54
*name * is the unique name for the requested shared memory, specified as
55
55
a string. When creating a new shared memory block, if ``None `` (the
@@ -62,28 +62,28 @@ copying of data.
62
62
memory block. Because some platforms choose to allocate chunks of memory
63
63
based upon that platform's memory page size, the exact size of the shared
64
64
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.
66
66
67
67
.. method :: close()
68
68
69
69
Closes access to the shared memory from this instance. In order to
70
70
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
73
73
destroyed.
74
74
75
75
.. method :: unlink()
76
76
77
77
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
79
79
called once (and only once) across all processes which have need
80
80
for the shared memory block. After requesting its destruction, a
81
81
shared memory block may or may not be immediately destroyed and
82
82
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
84
84
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.
87
87
88
88
.. attribute :: buf
89
89
@@ -126,7 +126,7 @@ instances::
126
126
127
127
The following example demonstrates a practical use of the :class: `SharedMemory `
128
128
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:
130
130
131
131
.. doctest ::
132
132
:options: +SKIP
@@ -178,43 +178,43 @@ same ``numpy.ndarray`` from two distinct Python shells:
178
178
.. class :: SharedMemoryManager([address[, authkey]])
179
179
:module: multiprocessing.managers
180
180
181
- A subclass of :class: `~ multiprocessing.managers.BaseManager ` which can be
181
+ A subclass of :class: `multiprocessing.managers.BaseManager ` which can be
182
182
used for the management of shared memory blocks across processes.
183
183
184
184
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.
186
186
This new process's sole purpose is to manage the life cycle
187
187
of all shared memory blocks created through it. To trigger the release
188
188
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
194
194
and trigger the freeing of shared memory resources.
195
195
196
196
This class provides methods for creating and returning :class: `SharedMemory `
197
197
instances and for creating a list-like object (:class: `ShareableList `)
198
198
backed by shared memory.
199
199
200
- Refer to :class: `multiprocessing.managers.BaseManager ` for a description
200
+ Refer to :class: `~ multiprocessing.managers.BaseManager ` for a description
201
201
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
203
203
from other processes.
204
204
205
205
.. method :: SharedMemory(size)
206
206
207
207
Create and return a new :class: `SharedMemory ` object with the
208
- specified `` size `` in bytes.
208
+ specified * size * in bytes.
209
209
210
210
.. method :: ShareableList(sequence)
211
211
212
212
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 * .
214
214
215
215
216
216
The following example demonstrates the basic mechanisms of a
217
- :class: `SharedMemoryManager `:
217
+ :class: `~multiprocessing.managers. SharedMemoryManager `:
218
218
219
219
.. doctest ::
220
220
:options: +SKIP
@@ -232,9 +232,9 @@ The following example demonstrates the basic mechanisms of a
232
232
>>> smm.shutdown() # Calls unlink() on sl, raw_shm, and another_sl
233
233
234
234
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:
238
238
239
239
.. doctest ::
240
240
:options: +SKIP
@@ -250,38 +250,46 @@ needed:
250
250
... p2.join() # Wait for all work to complete in both processes
251
251
... total_result = sum (sl) # Consolidate the partial results now in sl
252
252
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.
256
257
257
258
258
- .. class :: ShareableList(sequence=None, \ *, name=None)
259
+ .. class :: ShareableList(sequence=None, *, name=None)
259
260
260
261
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
268
276
via slicing.
269
277
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.
271
279
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.
273
281
274
282
*name * is the unique name for the requested shared memory, as described
275
283
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 ``.
278
286
279
287
.. note ::
280
288
281
289
A known issue exists for :class: `bytes ` and :class: `str ` values.
282
290
If they end with ``\x00 `` nul bytes or characters, those may be
283
291
*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
285
293
considered a bug and may go away in the future. See :gh: `106939 `.
286
294
287
295
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
307
315
308
316
.. method :: count(value)
309
317
310
- Returns the number of occurrences of `` value `` .
318
+ Returns the number of occurrences of * value * .
311
319
312
320
.. method :: index(value)
313
321
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.
316
324
317
325
.. attribute :: format
318
326
@@ -372,8 +380,8 @@ behind it:
372
380
>>> c.shm.close()
373
381
>>> c.shm.unlink()
374
382
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
377
385
can be pickled and unpickled if needed.
378
386
Note, that it will still be the same shared object.
379
387
This happens, because the deserialized object has
0 commit comments