mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 10:19:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

[3.12] gh-106939: document ShareableList nul-strip quirk. (GH-107266) (#107269)

Browse source 
gh-106939: document ShareableList nul-strip quirk. (GH-107266)

* gh-106939: document ShareableList nul-strip quirk.
* Mention the `int` size constraint.
(cherry picked from commit 70dc009469)

Co-authored-by: Gregory P. Smith <greg@krypto.org>
This commit is contained in:
Miss Islington (bot) 2023-07-25 14:19:25 -07:00 • committed by GitHub
parent c3c8916dea
commit 0107731a06
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 37 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

44
Doc/library/multiprocessing.shared_memory.rst
View file

@ -255,16 +255,17 @@ shared memory blocks created using that manager are all released when the
:keyword:`with` statement's code block finishes execution. :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 Provides a mutable list-like object where all values stored within are
stored in a shared memory block. This constrains storable values to stored in a shared memory block. This constrains storable values to
only the ``int``, ``float``, ``bool``, ``str`` (less than 10M bytes each), only the ``int`` (signed 64-bit), ``float``, ``bool``, ``str`` (less
``bytes`` (less than 10M bytes each), and ``None`` built-in data types. than 10M bytes each when encoded as utf-8), ``bytes`` (less than 10M
It also notably differs from the built-in ``list`` type in that these bytes each), and ``None`` built-in data types. It also notably
lists can not change their overall length (i.e. no append, insert, etc.) differs from the built-in ``list`` type in that these lists can not
and do not support the dynamic creation of new :class:`ShareableList` change their overall length (i.e. no append, insert, etc.) and do not
instances via slicing. 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 ``ShareableList`` full of values.
Set to ``None`` to instead attach to an already existing Set to ``None`` to instead attach to an already existing
@ -275,6 +276,35 @@ shared memory blocks created using that manager are all released when the
existing ``ShareableList``, specify its shared memory block's unique existing ``ShareableList``, specify its shared memory block's unique
name while leaving ``sequence`` set to ``None``. 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
considered a bug and may go away in the future. See :gh:`106939`.
For applications where rstripping of trailing nulls is a problem,
work around it by always unconditionally appending an extra non-0
byte to the end of such values when storing and unconditionally
removing it when fetching:
.. doctest::
>>> from multiprocessing import shared_memory
>>> nul_bug_demo = shared_memory.ShareableList(['?\x00', b'\x03\x02\x01\x00\x00\x00'])
>>> nul_bug_demo[0]
'?'
>>> nul_bug_demo[1]
b'\x03\x02\x01'
>>> nul_bug_demo.shm.unlink()
>>> padded = shared_memory.ShareableList(['?\x00\x07', b'\x03\x02\x01\x00\x00\x00\x07'])
>>> padded[0][:-1]
'?\x00'
>>> padded[1][:-1]
b'\x03\x02\x01\x00\x00\x00'
>>> padded.shm.unlink()
.. method:: count(value) .. method:: count(value)
Returns the number of occurrences of ``value``. Returns the number of occurrences of ``value``.