Repository navigation
gh-156866: Document that pack_into() does not guarantee memory access shape - #162078
Open
themythofsisyphusjayant wants to merge 1 commit into
Open
themythofsisyphusjayant wants to merge 1 commit into
themythofsisyphusjayant wants to merge 1 commit into
Conversation
Documentation build overview
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The
struct.pack_into()documentation says it writes the packed bytes intoa writable buffer, but says nothing about the underlying memory accesses
used to perform the write. For ordinary memory that does not matter, but it
is misleading when the buffer is backed by memory-mapped I/O (MMIO), where
the number, width, and ordering of actual memory accesses can be
semantically significant — a single
pack_into("<I", ...)call was observedto produce three native stores.
This adds a note to the
pack_into()documentation (using the wordingsuggested in the issue):
pack_into()specifies the packed bytes writtento the buffer, but does not guarantee the number, width, or ordering of the
underlying native memory accesses. Writable buffers backed by MMIO should
not be treated as exact-width register access interfaces. The
Struct.pack_intomethod needs no change — it is documented as identical to the function.
Checked by building the page with Sphinx (9.1.1, from
Doc/requirements.txt): the page renders with the new note. The only buildwarnings are pre-existing single-file-build artifacts, identical before and
after the change.
Disclosure: I used an AI coding assistant to help prepare this change, and
reviewed the diff myself before submitting.