gh-111968: Introduce _PyFreeListState and _PyFreeListState_GET API (gh-113584)

Include/internal/pycore_freelist.h

@@ -0,0 +1,35 @@
+#ifndef Py_INTERNAL_FREELIST_H
+#define Py_INTERNAL_FREELIST_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef Py_BUILD_CORE
+#  error "this header requires Py_BUILD_CORE define"
+#endif
+
+#ifndef WITH_FREELISTS
+// without freelists
+#  define PyList_MAXFREELIST 0
+#endif
+
+/* Empty list reuse scheme to save calls to malloc and free */
+#ifndef PyList_MAXFREELIST
+#  define PyList_MAXFREELIST 80
+#endif
+
+struct _Py_list_state {
+#if PyList_MAXFREELIST > 0
+    PyListObject *free_list[PyList_MAXFREELIST];
+    int numfree;
+#endif
+};
+
+typedef struct _Py_freelist_state {
+    struct _Py_list_state list;
+} _PyFreeListState;
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* !Py_INTERNAL_FREELIST_H */

Include/internal/pycore_gc.h

@@ -8,6 +8,8 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
+#include "pycore_freelist.h"   // _PyFreeListState
+
 /* GC information is stored BEFORE the object structure. */
 typedef struct {
     // Pointer to next object in the list.
@@ -238,9 +240,11 @@ extern PyObject *_PyGC_GetObjects(PyInterpreterState *interp, Py_ssize_t generat
 extern PyObject *_PyGC_GetReferrers(PyInterpreterState *interp, PyObject *objs);
 
 // Functions to clear types free lists
+extern void _PyGC_ClearAllFreeLists(PyInterpreterState *interp);
+extern void _Py_ClearFreeLists(_PyFreeListState *state, int is_finalization);
 extern void _PyTuple_ClearFreeList(PyInterpreterState *interp);
 extern void _PyFloat_ClearFreeList(PyInterpreterState *interp);
-extern void _PyList_ClearFreeList(PyInterpreterState *interp);
+extern void _PyList_ClearFreeList(_PyFreeListState *state, int is_finalization);
 extern void _PyDict_ClearFreeList(PyInterpreterState *interp);
 extern void _PyAsyncGen_ClearFreeLists(PyInterpreterState *interp);
 extern void _PyContext_ClearFreeList(PyInterpreterState *interp);

Include/internal/pycore_interp.h

@@ -179,6 +179,9 @@ struct _is {
     // One bit is set for each non-NULL entry in code_watchers
     uint8_t active_code_watchers;
 
+#if !defined(Py_GIL_DISABLED)
+    struct _Py_freelist_state freelist_state;
+#endif
     struct _py_object_state object_state;
     struct _Py_unicode_state unicode;
     struct _Py_float_state float_state;
@@ -190,7 +193,6 @@ struct _is {
     PySliceObject *slice_cache;
 
     struct _Py_tuple_state tuple;
-    struct _Py_list_state list;
     struct _Py_dict_state dict_state;
     struct _Py_async_gen_state async_gen;
     struct _Py_context_state context;

Include/internal/pycore_list.h

@@ -8,6 +8,7 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
+#include "pycore_freelist.h"  // _PyFreeListState
 
 extern PyObject* _PyList_Extend(PyListObject *, PyObject *);
 extern void _PyList_DebugMallocStats(FILE *out);
@@ -15,28 +16,9 @@ extern void _PyList_DebugMallocStats(FILE *out);
 
 /* runtime lifecycle */
 
-extern void _PyList_Fini(PyInterpreterState *);
+extern void _PyList_Fini(_PyFreeListState *);
 
 
-/* other API */
-
-#ifndef WITH_FREELISTS
-// without freelists
-#  define PyList_MAXFREELIST 0
-#endif
-
-/* Empty list reuse scheme to save calls to malloc and free */
-#ifndef PyList_MAXFREELIST
-#  define PyList_MAXFREELIST 80
-#endif
-
-struct _Py_list_state {
-#if PyList_MAXFREELIST > 0
-    PyListObject *free_list[PyList_MAXFREELIST];
-    int numfree;
-#endif
-};
-
 #define _PyList_ITEMS(op) _Py_RVALUE(_PyList_CAST(op)->ob_item)
 
 extern int

Include/internal/pycore_pystate.h

@@ -8,7 +8,9 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
+#include "pycore_freelist.h"      // _PyFreeListState
 #include "pycore_runtime.h"       // _PyRuntime
+#include "pycore_tstate.h"        // _PyThreadStateImpl
 
 
 // Values for PyThreadState.state. A thread must be in the "attached" state
@@ -239,6 +241,20 @@ PyAPI_FUNC(const PyConfig*) _Py_GetConfig(void);
 // See also PyInterpreterState_Get() and _PyInterpreterState_GET().
 extern PyInterpreterState* _PyGILState_GetInterpreterStateUnsafe(void);
 
+static inline _PyFreeListState* _PyFreeListState_GET(void)
+{
+    PyThreadState *tstate = _PyThreadState_GET();
+#ifdef Py_DEBUG
+    _Py_EnsureTstateNotNULL(tstate);
+#endif
+
+#ifdef Py_GIL_DISABLED
+    return &((_PyThreadStateImpl*)tstate)->freelist_state;
+#else
+    return &tstate->interp->freelist_state;
+#endif
+}
+
 #ifdef __cplusplus
 }
 #endif

Include/internal/pycore_tstate.h

@@ -8,6 +8,7 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
+#include "pycore_freelist.h"      // struct _Py_freelist_state
 #include "pycore_mimalloc.h"      // struct _mimalloc_thread_state
 
 
@@ -20,6 +21,7 @@ typedef struct _PyThreadStateImpl {
 
 #ifdef Py_GIL_DISABLED
     struct _mimalloc_thread_state mimalloc;
+    struct _Py_freelist_state freelist_state;
 #endif
 
 } _PyThreadStateImpl;

Makefile.pre.in

@@ -418,6 +418,8 @@ PYTHON_OBJS=	\
 		Python/frozenmain.o \
 		Python/future.o \
 		Python/gc.o \
+		Python/gc_free_threading.o \
+		Python/gc_gil.o \
 		Python/getargs.o \
 		Python/getcompiler.o \
 		Python/getcopyright.o \
@@ -1828,6 +1830,7 @@ PYTHON_HEADERS= \
 		$(srcdir)/Include/internal/pycore_floatobject.h \
 		$(srcdir)/Include/internal/pycore_format.h \
 		$(srcdir)/Include/internal/pycore_frame.h \
+		$(srcdir)/Include/internal/pycore_freelist.h \
 		$(srcdir)/Include/internal/pycore_function.h \
 		$(srcdir)/Include/internal/pycore_genobject.h \
 		$(srcdir)/Include/internal/pycore_getopt.h \

Objects/listobject.c

@@ -24,8 +24,9 @@ _Py_DECLARE_STR(list_err, "list index out of range");
 static struct _Py_list_state *
 get_list_state(void)
 {
-    PyInterpreterState *interp = _PyInterpreterState_GET();
-    return &interp->list;
+    _PyFreeListState *state = _PyFreeListState_GET();
+    assert(state != NULL);
+    return &state->list;
 }
 #endif
 
@@ -120,26 +121,25 @@ list_preallocate_exact(PyListObject *self, Py_ssize_t size)
 }
 
 void
-_PyList_ClearFreeList(PyInterpreterState *interp)
+_PyList_ClearFreeList(_PyFreeListState *freelist_state, int is_finalization)
 {
 #if PyList_MAXFREELIST > 0
-    struct _Py_list_state *state = &interp->list;
-    while (state->numfree) {
+    struct _Py_list_state *state = &freelist_state->list;
+    while (state->numfree > 0) {
         PyListObject *op = state->free_list[--state->numfree];
         assert(PyList_CheckExact(op));
         PyObject_GC_Del(op);
     }
+    if (is_finalization) {
+        state->numfree = -1;
+    }
 #endif
 }
 
 void
-_PyList_Fini(PyInterpreterState *interp)
+_PyList_Fini(_PyFreeListState *state)
 {
-    _PyList_ClearFreeList(interp);
-#if defined(Py_DEBUG) && PyList_MAXFREELIST > 0
-    struct _Py_list_state *state = &interp->list;
-    state->numfree = -1;
-#endif
+    _PyList_ClearFreeList(state, 1);
 }
 
 /* Print summary info about the state of the optimized allocator */

PCbuild/_freeze_module.vcxproj

@@ -208,6 +208,8 @@
     <ClCompile Include="..\Python\frame.c" />
     <ClCompile Include="..\Python\future.c" />
     <ClCompile Include="..\Python\gc.c" />
+    <ClCompile Include="..\Python\gc_gil.c" />
+    <ClCompile Include="..\Python\gc_free_threading.c" />
     <ClCompile Include="..\Python\getargs.c" />
     <ClCompile Include="..\Python\getcompiler.c" />
     <ClCompile Include="..\Python\getcopyright.c" />

PCbuild/_freeze_module.vcxproj.filters

@@ -169,6 +169,12 @@
     <ClCompile Include="..\Python\gc.c">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="..\Python\gc_free_threading.c">
+      <Filter>Source Files</Filter>
+    </ClCompile>
+    <ClCompile Include="..\Python\gc_gil.c">
+      <Filter>Source Files</Filter>
+    </ClCompile>
     <ClCompile Include="..\Modules\gcmodule.c">
       <Filter>Source Files</Filter>
     </ClCompile>

PCbuild/pythoncore.vcxproj

@@ -231,6 +231,7 @@
     <ClInclude Include="..\Include\internal\pycore_floatobject.h" />
     <ClInclude Include="..\Include\internal\pycore_format.h" />
     <ClInclude Include="..\Include\internal\pycore_frame.h" />
+    <ClInclude Include="..\Include\internal\pycore_freelist.h" />
     <ClInclude Include="..\Include\internal\pycore_function.h" />
     <ClInclude Include="..\Include\internal\pycore_gc.h" />
     <ClInclude Include="..\Include\internal\pycore_genobject.h" />
@@ -568,6 +569,8 @@
     </ClCompile>
     <ClCompile Include="..\Python\future.c" />
     <ClCompile Include="..\Python\gc.c" />
+    <ClCompile Include="..\Python\gc_free_threading.c" />
+    <ClCompile Include="..\Python\gc_gil.c" />
     <ClCompile Include="..\Python\getargs.c" />
     <ClCompile Include="..\Python\getcompiler.c" />
     <ClCompile Include="..\Python\getcopyright.c" />

PCbuild/pythoncore.vcxproj.filters

@@ -618,6 +618,12 @@
     <ClInclude Include="..\Include\internal\pycore_format.h">
       <Filter>Include\internal</Filter>
     </ClInclude>
+    <ClInclude Include="..\Include\internal\pycore_frame.h">
+      <Filter>Include\internal</Filter>
+    </ClInclude>
+    <ClInclude Include="..\Include\internal\pycore_freelist.h">
+      <Filter>Include\internal</Filter>
+    </ClInclude>
     <ClInclude Include="..\Include\internal\pycore_function.h">
       <Filter>Include\internal</Filter>
     </ClInclude>
@@ -1286,6 +1292,12 @@
     <ClCompile Include="..\Python\gc.c">
       <Filter>Python</Filter>
     </ClCompile>
+    <ClCompile Include="..\Python\gc_free_threading.c">
+      <Filter>Python</Filter>
+    </ClCompile>
+    <ClCompile Include="..\Python\gc_gil.c">
+      <Filter>Python</Filter>
+    </ClCompile>
     <ClCompile Include="..\Python\getargs.c">
       <Filter>Python</Filter>
     </ClCompile>

Python/gc.c

@@ -1019,21 +1019,6 @@ delete_garbage(PyThreadState *tstate, GCState *gcstate,
     }
 }
 
-/* Clear all free lists
- * All free lists are cleared during the collection of the highest generation.
- * Allocated items in the free list may keep a pymalloc arena occupied.
- * Clearing the free lists may give back memory to the OS earlier.
- */
-static void
-clear_freelists(PyInterpreterState *interp)
-{
-    _PyTuple_ClearFreeList(interp);
-    _PyFloat_ClearFreeList(interp);
-    _PyList_ClearFreeList(interp);
-    _PyDict_ClearFreeList(interp);
-    _PyAsyncGen_ClearFreeLists(interp);
-    _PyContext_ClearFreeList(interp);
-}
 
 // Show stats for objects in each generations
 static void
@@ -1449,7 +1434,7 @@ gc_collect_main(PyThreadState *tstate, int generation, _PyGC_Reason reason)
     /* Clear free list only during the collection of the highest
      * generation */
     if (generation == NUM_GENERATIONS-1) {
-        clear_freelists(tstate->interp);
+        _PyGC_ClearAllFreeLists(tstate->interp);
     }
 
     if (_PyErr_Occurred(tstate)) {

Python/gc_free_threading.c

@@ -0,0 +1,32 @@
+#include "Python.h"
+#include "pycore_pystate.h"   // _PyFreeListState_GET()
+#include "pycore_tstate.h"    // _PyThreadStateImpl
+
+#ifdef Py_GIL_DISABLED
+
+/* Clear all free lists
+ * All free lists are cleared during the collection of the highest generation.
+ * Allocated items in the free list may keep a pymalloc arena occupied.
+ * Clearing the free lists may give back memory to the OS earlier.
+ * Free-threading version: Since freelists are managed per thread,
+ * GC should clear all freelists by traversing all threads.
+ */
+void
+_PyGC_ClearAllFreeLists(PyInterpreterState *interp)
+{
+    _PyTuple_ClearFreeList(interp);
+    _PyFloat_ClearFreeList(interp);
+    _PyDict_ClearFreeList(interp);
+    _PyAsyncGen_ClearFreeLists(interp);
+    _PyContext_ClearFreeList(interp);
+
+    HEAD_LOCK(&_PyRuntime);
+    _PyThreadStateImpl *tstate = (_PyThreadStateImpl *)interp->threads.head;
+    while (tstate != NULL) {
+        _Py_ClearFreeLists(&tstate->freelist_state, 0);
+        tstate = (_PyThreadStateImpl *)tstate->base.next;
+    }
+    HEAD_UNLOCK(&_PyRuntime);
+}
+
+#endif

Python/gc_gil.c

@@ -0,0 +1,23 @@
+#include "Python.h"
+#include "pycore_pystate.h"   // _Py_ClearFreeLists()
+
+#ifndef Py_GIL_DISABLED
+
+/* Clear all free lists
+ * All free lists are cleared during the collection of the highest generation.
+ * Allocated items in the free list may keep a pymalloc arena occupied.
+ * Clearing the free lists may give back memory to the OS earlier.
+ */
+void
+_PyGC_ClearAllFreeLists(PyInterpreterState *interp)
+{
+    _PyTuple_ClearFreeList(interp);
+    _PyFloat_ClearFreeList(interp);
+    _PyDict_ClearFreeList(interp);
+    _PyAsyncGen_ClearFreeLists(interp);
+    _PyContext_ClearFreeList(interp);
+
+    _Py_ClearFreeLists(&interp->freelist_state, 0);
+}
+
+#endif

Python/pylifecycle.c

@@ -1752,13 +1752,16 @@ finalize_interp_types(PyInterpreterState *interp)
     _PyUnicode_ClearInterned(interp);
 
     _PyDict_Fini(interp);
-    _PyList_Fini(interp);
     _PyTuple_Fini(interp);
 
     _PySlice_Fini(interp);
 
     _PyUnicode_Fini(interp);
     _PyFloat_Fini(interp);
+
+    _PyFreeListState *state = _PyFreeListState_GET();
+    _PyList_Fini(state);
+
 #ifdef Py_DEBUG
     _PyStaticObjects_CheckRefcnt(interp);
 #endif

Python/pystate.c

@@ -1455,6 +1455,12 @@ clear_datastack(PyThreadState *tstate)
     }
 }
 
+void
+_Py_ClearFreeLists(_PyFreeListState *state, int is_finalization)
+{
+    _PyList_ClearFreeList(state, is_finalization);
+}
+
 void
 PyThreadState_Clear(PyThreadState *tstate)
 {
@@ -1537,6 +1543,11 @@ PyThreadState_Clear(PyThreadState *tstate)
         // don't call _PyInterpreterState_SetNotRunningMain() yet.
         tstate->on_delete(tstate->on_delete_data);
     }
+#ifdef Py_GIL_DISABLED
+    // Each thread should clear own freelists in free-threading builds.
+    _PyFreeListState *freelist_state = &((_PyThreadStateImpl*)tstate)->freelist_state;
+    _Py_ClearFreeLists(freelist_state, 0);
+#endif
 
     _PyThreadState_ClearMimallocHeaps(tstate);