Skip to content

Commit 67e0550

Browse files
committed
docs: clarify chunked deque copy guarantees
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 gh-161850.
1 parent da66db3 commit 67e0550

2 files changed

Lines changed: 11 additions & 8 deletions

File tree

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
Speed up :func:`list`, :meth:`list.extend`, :meth:`str.join` and unpacking of
2-
a :class:`collections.deque` by copying its items under a single lock in the
3-
:term:`free-threaded build`.
2+
a :class:`collections.deque` by copying up to 64 items per critical section
3+
in the :term:`free-threaded build`. Release the locks between chunks and
4+
check for iterator-invalidating mutations before each chunk.

‎Modules/_collectionsmodule.c‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2106,12 +2106,14 @@ static PyType_Spec dequeiter_spec = {
21062106
* functions below instead copy up to DEQUE_EXTEND_CHUNK items per critical
21072107
* section on (list, deque).
21082108
*
2109-
* Copying in bounded chunks, rather than all at once, keeps the time the
2110-
* deque's lock is held independent of the deque's length, so threads waiting
2111-
* for it (for example a writer while other threads keep copying the deque)
2112-
* are not starved. Between chunks the copy behaves exactly like iteration:
2113-
* the deque's state is checked again and a mutation raises RuntimeError, as
2114-
* next() would. No user code runs during either form of iteration.
2109+
* Bounded chunks amortize the per-element locking cost while releasing the
2110+
* critical section between groups of items. This bounds element transfer,
2111+
* not total lock duration: initial list capacity reservation can still do
2112+
* work proportional to the remaining size while holding both locks.
2113+
* Between chunks, iterator-invalidating changes to deque->state raise
2114+
* RuntimeError using the same check as next(). State-preserving mutations
2115+
* are not rejected, and no atomic snapshot or starvation guarantee is made.
2116+
* The element-copy loop does not call Python iteration methods.
21152117
*/
21162118
#define DEQUE_EXTEND_CHUNK BLOCKLEN
21172119

0 commit comments

Comments
 (0)