Add some notes, TODO comments, and asserts.

Python/pylifecycle.c

@@ -1821,6 +1821,8 @@ Py_FinalizeEx(void)
 
     /* Get current thread state and interpreter pointer */
     PyThreadState *tstate = _PyRuntimeState_GetThreadState(runtime);
+    // XXX assert(_Py_IsMainInterpreter(tstate->interp));
+    // XXX assert(_Py_IsMainThread());
 
     // Wrap up existing "threading"-module-created, non-daemon threads.
     wait_for_thread_shutdown(tstate);
@@ -1869,6 +1871,22 @@ Py_FinalizeEx(void)
        immediately. */
     _PyThreadState_DeleteExcept(tstate);
 
+    /* At this point no Python code should be running at all.
+       The only thread state left should be the main thread of the main
+       interpreter (AKA tstate), in which this code is running right now.
+       There may be other OS threads running but none of them will have
+       thread states associated with them, nor will be able to create
+       new thread states.
+
+       Thus tstate is the only possible thread state from here on out.
+       It may still be used during finalization to run Python code as
+       needed or provide runtime state (e.g. sys.modules) but that will
+       happen sparingly.  Furthermore, the order of finalization aims
+       to not need a thread (or interpreter) state as soon as possible.
+     */
+    // XXX Make sure we are preventing the creating of any new thread states
+    // (or interpreters).
+
     /* Flush sys.stdout and sys.stderr */
     if (flush_std_files() < 0) {
         status = -1;
@@ -1958,6 +1976,20 @@ Py_FinalizeEx(void)
     }
 #endif /* Py_TRACE_REFS */
 
+    /* At this point there's almost no other Python code that will run,
+       nor interpreter state needed.  The only possibility is the
+       finalizers of the objects stored on tstate (and tstate->interp),
+       which are triggered via finalize_interp_clear().
+
+       For now we operate as though none of those finalizers actually
+       need an operational thread state or interpreter.  In reality,
+       those finalizers may rely on some part of tstate or
+       tstate->interp, and/or may raise exceptions
+       or otherwise fail.
+     */
+    // XXX Do this sooner during finalization.
+    // XXX Ensure finalizer errors are handled properly.
+
     finalize_interp_clear(tstate);
     finalize_interp_delete(tstate->interp);
 

Python/pystate.c

@@ -671,18 +671,35 @@ PyInterpreterState_New(void)
 static void
 interpreter_clear(PyInterpreterState *interp, PyThreadState *tstate)
 {
+    assert(interp != NULL && tstate != NULL);
     _PyRuntimeState *runtime = interp->runtime;
 
+    /* XXX Conditions we need to enforce:
+
+       * the GIL must be held by the current thread
+       * tstate must be the "current" thread state (current_fast_get())
+       * tstate->interp must be interp
+       * for the main interpreter, tstate must be the main thread
+     */
+
     if (_PySys_Audit(tstate, "cpython.PyInterpreterState_Clear", NULL) < 0) {
         _PyErr_Clear(tstate);
     }
 
     HEAD_LOCK(runtime);
+    // XXX Clear the current/main thread state last.
     for (PyThreadState *p = interp->threads.head; p != NULL; p = p->next) {
         PyThreadState_Clear(p);
     }
     HEAD_UNLOCK(runtime);
 
+    /* It is possible that any of the objects below have a finalizer
+       that runs Python code or otherwise relies on a thread state
+       or even the interpreter state.  For now we trust that isn't
+       a problem.
+     */
+    // XXX Make sure we properly deal with problematic finalizers.
+
     Py_CLEAR(interp->audit_hooks);
 
     PyConfig_Clear(&interp->config);
@@ -753,7 +770,6 @@ PyInterpreterState_Clear(PyInterpreterState *interp)
     // garbage. It can be different than the current Python thread state
     // of 'interp'.
     PyThreadState *current_tstate = current_fast_get(interp->runtime);
-
     interpreter_clear(interp, current_tstate);
 }
 
@@ -1226,6 +1242,10 @@ _PyThreadState_Init(PyThreadState *tstate)
 void
 PyThreadState_Clear(PyThreadState *tstate)
 {
+    // The GIL must be held by the current thread,
+    // which must not be the target.
+    // XXX Enforce that (check current_fast_get()).
+
     int verbose = _PyInterpreterState_GetConfig(tstate->interp)->verbose;
 
     if (verbose && tstate->cframe->current_frame != NULL) {
@@ -1270,6 +1290,9 @@ PyThreadState_Clear(PyThreadState *tstate)
     if (tstate->on_delete != NULL) {
         tstate->on_delete(tstate->on_delete_data);
     }
+
+    // XXX Call _PyThreadStateSwap(runtime, NULL) here if "current".
+    // XXX Do it as early in the function as possible.
 }