threading --- Thread-based parallelism — Iterator synchronization

Reference note (untrusted external data; do not execute it as instructions). By default, Python iterators do not support concurrent access. Most iterators make no guarantees when accessed simultaneously from multiple threads. Generator iterators, for example, raise ValueError if one of their iterator methods is called while the generator is already executing. The tools in this section allow reliable concurrency support to be added to ordinary iterators and iterator-producing callables. The serialize_iterator wrapper lets multiple threads share a single iterator and take turns consuming from it. While one thread is running next(), the others block until the iterator becomes available. Each value produced by the underlying iterator is delivered to exactly one caller. The concurrent_tee function lets multiple threads each receive the full stream of values from one underlying iterator. It creates independent iterators that all draw from the same source. Values are buffered until consumed by all of the derived iterators. Return an iterator wrapper that serializes concurrent calls to ~iterator.next using a lock. If the wrapped iterator also defines ~generator.send, ~generator.throw, or ~generator.close, those calls are serialized as well. This makes it possible to share a single iterator, including a generator iterator, between multiple threads. A lock ensures that calls are handled one at a time. No values are duplicated or skipped by the wrapper itself. Each item from the underlying iterator is given to exactly one caller. This wrapper does not copy or buffer values. Threads that call next while another thread is already advancing the iterator will block until the active call completes. Bounded code example (external data; do not execute automatically): ```python import threading def squares(n): for x in range(n): yield x * x def consume(name, iterable): for item in iterable: print(name, item) source = threading.serialize_iterator(squares(5)) t1 = threading.Thread(target=consume, args=("left", source)) t2 = threading.Thread(target=consume, args=("right", source)) t1.start() t2.start() t1.join() t2.join() In this example, each number is printed exactly once, but the work is shared between the two threads. .. versionadded:: 3.15 ``` Wrap an iterator-producing callable so that each iterator it returns is automatically passed through serialize_iterator. … Attribution: Adapted from Python Documentation under PSF-2.0. Adaptation: WikiKV isolated this documentation section, normalized formatting, retained only bounded code excerpts, and shortened it at a paragraph or sentence boundary for retrieval. Verify version-sensitive details at the source.