gh-124210: Add introduction to docs for threading module #127046
Conversation
|
@merwok could you check the changes of this PR? |
| units of a process) concurrently within a single process. It allows for the | ||
| creation and management of threads, making it possible to execute tasks in | ||
| parallel, sharing memory space. Threads are particularly useful when tasks are | ||
| I/O-bound, such as reading from or writing to files, or making network requests, |
There was a problem hiding this comment.
This caught me off guard. Typically, threads are for speeding up CPU bound operations, and something like asyncio is for I/O bound tasks. Threads being more efficient for I/O bound tasks is really only because of the GIL, but we're trying to get rid of that anyway.
| bypass the :term:`Global Interpreter Lock <global interpreter lock>`, the | ||
| threading module operates within a single process, meaning that all threads | ||
| share the same memory space. However, the GIL limits the performance gains of | ||
| threading when it comes to CPU-bound tasks, as only one thread can execute |
There was a problem hiding this comment.
Ah, here we are about CPU bound tasks. I think we should mention the experimental free-threaded builds here.
Doc/library/threading.rst
Outdated
| # Wait for all threads to finish | ||
| for t in threads: | ||
| t.join() | ||
|
|
||
| This module constructs higher-level threading interfaces on top of the lower |
There was a problem hiding this comment.
I think it looks kind of weird having all this technical information below the introduction. This, and the parts below it down to the note about WASI compatibility, should ideally go before the introduction.
There was a problem hiding this comment.
I looked at multiprocessing.rst as a reference and it's in the same order:
Introduction
------------
Common info about module
python code exampleor you mean information about This module constructs higher-level threading interfaces ... needs to be moved before Introduction?
There was a problem hiding this comment.
or you mean information about This module constructs higher-level threading interfaces ... needs to be moved before Introduction?
Yeah, as well as the stuff about compatibility, versionadded, and whatnot.
There was a problem hiding this comment.
like this?
📚 Documentation preview 📚: https://cpython-previews--127046.org.readthedocs.build/en/127046/library/threading.html#introduction
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
I chose to take courage and add not only a usage example but also an introduction to the documentation.
I was inspired by the documentation at https://docs.python.org/3/library/multiprocessing.html
This page also have introduction before basic example
📚 Documentation preview 📚: https://cpython-previews--127046.org.readthedocs.build/en/127046/library/threading.html#introduction