gh-124397: Add free-threading support for iterators.

[rhettinger]

---

📚 Documentation preview 📚: https://cpython-previews--148894.org.readthedocs.build/

• Issue: Strategy for Iterators in Free Threading #124397

[colesbury]

LGTM

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32503627 | 📁 Comparing fbae726 against main (76b3923)

🔍 Preview build

69 files changed · + 1 added · ± 68 modified

+Added

• c-api/sentinel.html

±Modified

• contents.html
• download.html
• genindex-B.html
• genindex-C.html
• genindex-D.html
• genindex-E.html
• genindex-F.html
• genindex-G.html
• genindex-H.html
• genindex-I.html
• and 58 more...

[vstinner]

I concur with @ZeroIntensity who wrote that threading is a bad place for this. I'm not sure that threading is a good home for the 3 added functions (serialize, synchronized, concurrent_tee). IMO itertools would be a better home for them.

For example, I would expect @threading.synchronized (which sounds like synchronized in Java) to work on any function, such as:

importthreadingclassDemo:
_next_id=0@threading.synchronizeddefget_id(self):
self._next_id+=1returnself._next_id

But calling get_id() fails with:

Traceback (most recent call last):
File "/home/vstinner/python/main/x.py", line 12, in <module>
print(demo.get_id())
~~~~~~~~~~~^^
File "/home/vstinner/python/main/Lib/threading.py", line 930, in inner
return serialize(iterator)
File "/home/vstinner/python/main/Lib/threading.py", line 869, in __init__
self._iterator = iter(iterable)
~~~~^^^^^^^^^^
TypeError: 'int' object is not iterable

concurrent_tee() sounds very specific, whereas currently threading only contains very generic tooling to write multithreaded code. itertools contains many functions, so should we expect to pop up more itertools functions in threading? As an user, it's uneasy for me to choose between threading.concurrent_tee() and itertools.tee() who are in two different modules. I would expect them to be in the same module, and I expect itertools.tee() to mention concurrent_tee() and explain when it should be used instead.

[rhettinger]

Here are some GRASP-like thoughts on which module these should go into.

These are only useful in the context of multithreaded programs. The threading module is where people look for tools to manage and synchronize concurrency conflicts.

The implementation of the tools is almost entirely about lock management and synchronized result buffering. There is almost no logic that isn't threading related.

In contrast, the itertools module is scoped to only include general purpose tools for creating iterators. Nothing in it has any thread management. Most of the tools are roughly equivalent to just a plain generator.

[ZeroIntensity]

I'd be able to live with these existing under threading, but as Victor said, serialize and synchronized are extremely misleading names when in the threading module. itertools.serialize and itertools.synchronized make sense because itertools implies that they're about iteration; on the other hand, threading does not. There isn't anything in their names that distinguishes these from general concurrency ideas.

If we're going to keep these under threading, let's call them something like serialize_iterator and synchronized_iterator.

[ZeroIntensity]

Thanks for humoring me.

@vstinner, are you comfortable with this living under threading, as long as "iterator" is in the name?

[ZeroIntensity]

LGTM, thank you!

The failing CI is due to a Ubuntu outage.