gh-124397: Add threading.iter_locked

[eendebakpt]

Continuation of #133272
Name was discussed in https://discuss.python.org/t/name-for-new-itertools-object-to-make-iterators-thread-safe/90394

• Issue: Strategy for Iterators in Free Threading #124397

---

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

[ZeroIntensity]

@serhiy-storchaka, what was the rationale behind putting this in the threading module? I'm not against it, but I'm more in favor of itertools because threading doesn't expose any other utilities like this. Maybe we should add a threading.util module?

[ZeroIntensity]

I'm not sure non_atomic_iterator is a good example of something that exists in the wild, because it's not thread-safe on GIL-ful builds either. The thread can arbitrarily switch during execution of Python code, so this would need a lock anyway if concurrent iteration were a use case. For free-threading, __next__ itself should have its own locking to prevent races. How was this design reached?

[serhiy-storchaka]

1. It depends on the threading lock.
2. There will be a different implementation in the asyncio module that uses an asyncio lock.

[ZeroIntensity]

1. It seems reasonable to add a lock_type parameter for different types of locking, e.g. Lock vs RLock.
2. Why can't there be itertools.serialize and then asyncio.async_serialize? asyncio reimplements plenty of things, so it wouldn't be particularly inconsistent/confusing.