Accept suggestions

Author: donBarbos

Doc/library/threading.rst

@@ -16,15 +16,15 @@ level :mod:`_thread` module.
 Introduction
 ------------
 
-The :mod:`threading` module provides a way to run multiple `threads
+The :mod:`!threading` module provides a way to run multiple `threads
 <https://en.wikipedia.org/wiki/Thread_(computing)>`_ (smaller
 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 file operations or making network requests,
+I/O bound, such as file operations or making network requests,
 where much of the time is spent waiting for external resources.
 
-A typical use case for :mod:`threading` includes managing a pool of worker
+A typical use case for :mod:`!threading` includes managing a pool of worker
 threads that can process multiple tasks concurrently.  Here's a basic example of
 creating and starting threads using :class:`~threading.Thread`::
 
@@ -91,20 +91,22 @@ creating and starting threads using :class:`~threading.Thread`::
    However, threading is still an appropriate model if you want to run
    multiple I/O-bound tasks simultaneously.
 
-GIL and Performance Considerations
+GIL and performance considerations
 ----------------------------------
 
 Unlike the :mod:`multiprocessing` module, which uses separate processes to
-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 :term:`GIL` limits the performance
-gains of threading when it comes to CPU-bound tasks, as only one thread can
-execute Python bytecode at a time. Despite this, threads remain a useful tool
-for achieving concurrency in many scenarios.
+bypass the :term:`global interpreter lock` (GIL), 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 Python bytecode at a time.
+Despite this, threads remain a useful tool for achieving concurrency in many
+scenarios.
 
 As of Python 3.13, experimental :term:`free-threaded <free threading>` builds
-can disable the :term:`GIL`, enabling true parallel execution of threads, but
-this feature is not available by default. (See :pep:`703`.)
+can disable the GIL, enabling true parallel execution of threads, but this
+feature is not available by default (see :pep:`703`).
+
+.. TODO: At some point this feature will become available by default.
 
 Reference
 ---------
@@ -124,7 +126,7 @@ This module defines the following functions:
 
    Return the current :class:`Thread` object, corresponding to the caller's thread
    of control.  If the caller's thread of control was not created through the
-   :mod:`threading` module, a dummy thread object with limited functionality is
+   :mod:`!threading` module, a dummy thread object with limited functionality is
    returned.
 
    The function ``currentThread`` is a deprecated alias for this function.
@@ -219,13 +221,13 @@ This module defines the following functions:
 
    .. index:: single: trace function
 
-   Set a trace function for all threads started from the :mod:`threading` module.
+   Set a trace function for all threads started from the :mod:`!threading` module.
    The *func* will be passed to  :func:`sys.settrace` for each thread, before its
    :meth:`~Thread.run` method is called.
 
 .. function:: settrace_all_threads(func)
 
-   Set a trace function for all threads started from the :mod:`threading` module
+   Set a trace function for all threads started from the :mod:`!threading` module
    and all Python threads that are currently executing.
 
    The *func* will be passed to  :func:`sys.settrace` for each thread, before its
@@ -248,13 +250,13 @@ This module defines the following functions:
 
    .. index:: single: profile function
 
-   Set a profile function for all threads started from the :mod:`threading` module.
+   Set a profile function for all threads started from the :mod:`!threading` module.
    The *func* will be passed to  :func:`sys.setprofile` for each thread, before its
    :meth:`~Thread.run` method is called.
 
 .. function:: setprofile_all_threads(func)
 
-   Set a profile function for all threads started from the :mod:`threading` module
+   Set a profile function for all threads started from the :mod:`!threading` module
    and all Python threads that are currently executing.
 
    The *func* will be passed to  :func:`sys.setprofile` for each thread, before its
@@ -319,7 +321,7 @@ when implemented, are mapped to module-level functions.
 All of the methods described below are executed atomically.
 
 
-Thread-Local Data
+Thread-local data
 ^^^^^^^^^^^^^^^^^
 
 Thread-local data is data whose values are thread specific.  To manage
@@ -342,7 +344,7 @@ The instance's values will be different for separate threads.
 
 .. _thread-objects:
 
-Thread Objects
+Thread objects
 ^^^^^^^^^^^^^^
 
 The :class:`Thread` class represents an activity that is run in a separate
@@ -577,7 +579,7 @@ since it is impossible to detect the termination of alien threads.
 
 .. _lock-objects:
 
-Lock Objects
+Lock objects
 ^^^^^^^^^^^^
 
 A primitive lock is a synchronization primitive that is not owned by a
@@ -670,7 +672,7 @@ All methods are executed atomically.
 
 .. _rlock-objects:
 
-RLock Objects
+RLock objects
 ^^^^^^^^^^^^^
 
 A reentrant lock is a synchronization primitive that may be acquired multiple
@@ -773,7 +775,7 @@ call release as many times the lock has been acquired can lead to deadlock.
 
 .. _condition-objects:
 
-Condition Objects
+Condition objects
 ^^^^^^^^^^^^^^^^^
 
 A condition variable is always associated with some kind of lock; this can be
@@ -945,7 +947,7 @@ item to the buffer only needs to wake up one consumer thread.
 
 .. _semaphore-objects:
 
-Semaphore Objects
+Semaphore objects
 ^^^^^^^^^^^^^^^^^
 
 This is one of the oldest synchronization primitives in the history of computer
@@ -1026,7 +1028,7 @@ Semaphores also support the :ref:`context management protocol <with-locks>`.
 
 .. _semaphore-examples:
 
-:class:`Semaphore` Example
+:class:`Semaphore` example
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Semaphores are often used to guard resources with limited capacity, for example,
@@ -1054,7 +1056,7 @@ causes the semaphore to be released more than it's acquired will go undetected.
 
 .. _event-objects:
 
-Event Objects
+Event objects
 ^^^^^^^^^^^^^
 
 This is one of the simplest mechanisms for communication between threads: one
@@ -1111,7 +1113,7 @@ method.  The :meth:`~Event.wait` method blocks until the flag is true.
 
 .. _timer-objects:
 
-Timer Objects
+Timer objects
 ^^^^^^^^^^^^^
 
 This class represents an action that should be run only after a certain amount
@@ -1149,7 +1151,7 @@ For example::
       only work if the timer is still in its waiting stage.
 
 
-Barrier Objects
+Barrier objects
 ^^^^^^^^^^^^^^^
 
 .. versionadded:: 3.2