Redo the abstract.

Author: ZeroIntensity

peps/pep-0788.rst

@@ -14,47 +14,25 @@ Post-History: `10-Mar-2025 <https://discuss.python.org/t/83959>`__,
 Abstract
 ========
 
-In Python, threads are able to interact with an interpreter (e.g., invoke the
-bytecode loop) through an :term:`attached thread state`. On with-GIL builds,
-only one thread can hold an attached thread state at once, which means that
-the thread holds the :term:`GIL`. On free-threaded builds, there can be
-an unbounded number of thread states attached, allowing for parallelism (because
-multiple threads can invoke the interpreter at once).
-
-With that in mind, attachment of thread states is a bit problematic in the C API.
-The C API currently provides two ways to acquire and attach a thread state for
-an interpreter:
-
-- :c:func:`PyGILState_Ensure` & :c:func:`PyGILState_Release`.
-- :c:func:`PyThreadState_New` & :c:func:`PyThreadState_Swap` (significantly
-  less common).
-
-The former, :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`,
-are the most common way to do this and have been the standard for over twenty
-years (:pep:`311`), but have a number of issues that have arisen over time:
-
-- Subinterpreters tend to have trouble with them, because in threads that
-  haven't ever had an attached thread state, :c:func:`PyGILState_Ensure`
-  will assume that the main interpreter was requested. This makes it
-  impossible for the thread to interact with the subinterpreter!
-- The phrase "GIL" is confusing for developers of free-threaded
-  extensions, because there's no GIL there, right? Even on free-threaded
-  builds, threads still needs a thread state to interact with the interpreter,
-  it's just that they don't have to wait on one-another to do so. These days,
-  the important thing that :c:func:`PyGILState_Ensure` does is get attach a
-  thread state, and acquiring the GIL is somewhat incidental.
-
-The other option, :c:func:`PyThreadState_New` and :c:func:`PyThreadState_Swap`,
-do solve those issues, but come with an additional problem with how thread state
-attachment works in the C API (that ``PyGILState`` also includes): if the
-thread is not the main thread, then the interpreter will randomly hang the
-thread during attachment if it starts finalizing. This is a problem for large
-applications that want to use their thread in addition to calling Python.
-
-This PEP intends to solve these issues by providing :c:func:`PyThreadState_Ensure`
-and :c:func:`PyThreadState_Release` as replacements for the existing functions,
-accompanied by some interpreter reference counting APIs that let thread states
-be acquired and attached in a thread-safe and predictable manner.
+In the C API, threads are able to interact with an interpreter by holding an
+:term:`attached thread state` for the current thread. This works well, but
+can get complicated when it comes to creating and attaching :term:`thread states`
+in a thread-safe manner.
+
+Specifically, the C API doesn't have any way to ensure that an interpreter
+is in a state where it can be called when creating and/or attaching a thread
+state. As such, attachment might hang the thread, or in subinterpreters, it
+might flat-out crash due to the interpreter's structure being deallocated.
+This can be a frustrating issue to deal with in large applications that
+want to execute Python code alongside some other native code.
+
+In addition, assumptions about which interpreter to use tend to be wrong
+inside of subinterpreters, primarily because :c:func:`PyGILState_Ensure`
+always creates a thread state for the main interpreter in threads where
+Python hasn't ever run.
+
+This PEP intends to solve these kinds issues by *reimagining* how we approach
+thread states in the C API.
 
 Terminology
 ===========