Skip to content

gh-161850: Copy deque items into lists in chunks - #161854

Open
113xiaoji wants to merge 7 commits into
python:mainfrom
113xiaoji:deque-bulk-list-extend
Open

113xiaoji wants to merge 7 commits into
python:mainfrom
113xiaoji:deque-bulk-list-extend

Conversation

@113xiaoji

@113xiaoji 113xiaoji commented Nov 12, 2026 •

Copy link
Copy Markdown

Summary

Depends on #161853. This branch includes that prerequisite, so the diff against main contains both changes. The follow-up adds fast paths for materializing a deque or the remaining items of a forward deque iterator into a list.

Transfer at most BLOCKLEN (64) elements per critical section on the list and deque, releasing the locks between chunks. This amortizes per-item locking without retaining the original one-shot element-copy critical section for the entire deque.

Refs #161850.

Changes

  • Add chunked fast paths for list(d), [*d], list.extend(d) and the iterator path used by str.join(d).
  • Recheck the deque's structural state before each chunk, raising RuntimeError on iterator-invalidating mutation, and advance shared iterator position/count under the deque lock.
  • Retain the per-interpreter hooks registered by _collections, with release/acquire publication for free-threaded access.
  • Preserve the generic fallback for subclasses overriding the supported iteration or length slots.
  • Add block-boundary, partially consumed iterator, subclass, allocation/refcount and concurrent copy/iteration coverage.
  • Update the implementation comment and NEWS entry to describe chunking and its actual guarantees.

Concurrency and tradeoffs

The 64-item bound applies to element transfer, not total lock duration: initial list capacity reservation still covers all remaining items while holding the locks. This does not guarantee bounded waiting or eliminate writer starvation for every workload.

State-preserving deque mutations are not rejected by the structural-state check. The operation does not promise an atomic snapshot or reproduce every interleaving of repeated next() calls. The supported built-in-slot paths avoid user-defined iteration/length callbacks; the element-copy loop does not call Python iteration methods.

On a CPython 3.14.6 backport on Kunpeng 950, the chunked revision substantially improves writer progress over the one-shot revision, while retaining private-buffer throughput gains. A matched three-block, 5-second, batch-1 stress test with a 65,536-element deque and seven readers plus one writer measured writer throughput of about 458,691 ops/s before bulk copying, 698 ops/s with one-shot copying, and 46,342 ops/s with chunking. Large shared deques therefore retain a significant contention tradeoff. These are backport measurements, not performance claims for this main-based port.

Validation

  • Source review and git diff --check pass. The latest follow-up changes only the implementation comment and NEWS; C content outside block comments is unchanged from R3 implementation revision da66db3b89ef3251647c80328785235c7722ea12.
  • Focused native checks on matching main-based debug standard/free-threaded builds passed for shared iterator consumers, concurrent destination-list changes and rotation-result contents. These checks supplement, rather than replace, the full test suite and sanitizer runs.
  • On implementation revision da66db3b89ef3251647c80328785235c7722ea12, lint and the generated-files job passed, including C globals, exported symbols, limited ABI and regeneration checks. See the current-head Checks tab for the latest complete CI status; results from the earlier pre-chunking revision are not presented as validation of R3.
  • Benchmark and output-validation measurements used the CPython 3.14.6 backport. R3 FT/standard and cross-platform comparisons measure the patched builds, not the isolated gain from this PR or its prerequisite.

Review is requested for the fast-path hook design, iterator/list concurrency behavior and chunking tradeoffs. The prerequisite remains open; this PR is not ready to merge independently.

AI tools assisted preparation, review and benchmark analysis.

113xiaoji and others added 4 commits November 12, 2026 14:52
In the free-threaded build, dequeiter_next(), dequereviter_next() and
dequeiter_reduce() entered a two-object critical section on the iterator
and its deque.  All writes to the iterator's state already happen while
holding the deque's lock, so the deque's critical section alone is enough
to serialize concurrent next() calls on a shared iterator.  This halves
the atomic read-modify-write operations per item.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
list(d), [*d], list.extend(d) and PySequence_Fast(d) -- and hence
str.join(d), which hands the deque's iterator to list.extend() --
fetched one item per tp_iternext call, each entering a critical section.
Add a fast path that copies all remaining items of a deque or a forward
deque iterator while holding the list's and the deque's critical sections
once.  The _collections module registers it with listobject.c, since the
deque type lives in that module.  The result is identical to running the
iterator to exhaustion: no user code runs, the mutation check matches
next(), and the list's allocation matches the generic path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@python-cla-bot

python-cla-bot Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

All commit authors signed the Contributor License Agreement.

CLA signed

113xiaoji and others added 3 commits November 12, 2026 16:10
Keep the mutable deque hook pointer in PyInterpreterState instead of
 a C global so check-c-globals accepts it. Preserve release/acquire
publication for concurrent free-threaded registration.

Validated with ordinary and free-threaded pydebug builds, the focused
C globals check, and deque/list/collections/embed/interpreter tests.

pythongh-161850
Copying a whole deque under one critical section holds the deque's lock
for O(n).  When several threads keep copying a shared deque, a writer
then rarely gets the lock: on a Kunpeng 950, 7 threads calling list(d)
on a 1000-item deque cut a rotate() writer's throughput by ~99% and
pushed its p99 latency to ~1 ms (the PyMutex fairness timeout).

Copy at most BLOCKLEN items per critical section instead.  Between
chunks the deque's state is checked again and a mutation raises
RuntimeError, exactly as next() does, so the observable behavior under
concurrent mutation is the same as iterating item by item.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Describe the 64-item bound as an element-transfer bound and retain the
initial capacity reservation and concurrent-mutation limitations.
Update the NEWS entry to describe chunked copying instead of one lock.

Refs pythongh-161850.
@113xiaoji 113xiaoji changed the title gh-161850: Copy a deque into a list under a single critical section gh-161850: Copy deque items into lists in chunks Nov 15, 2026
@113xiaoji
113xiaoji marked this pull request as ready for review November 15, 2026 12:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review type-feature A feature request or enhancement

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant