gh-106320: Remove private _PyTraceMalloc C API functions (#106324)

* Remove private _PyTraceMalloc C API functions: move them to the
  internal C API.
* Don't export most of these functions anymore, but still export
  _PyTraceMalloc_GetTraceback() used by tests.
* Rename Include/tracemalloc.h to Include/cpython/tracemalloc.h

Author: vstinner

Include/Python.h

@@ -103,7 +103,7 @@
 #include "pystrcmp.h"
 #include "fileutils.h"
 #include "cpython/pyfpe.h"
-#include "tracemalloc.h"
+#include "cpython/tracemalloc.h"
 #include "cpython/optimizer.h"
 
 #endif /* !Py_PYTHON_H */

Include/cpython/tracemalloc.h

@@ -0,0 +1,26 @@
+#ifndef Py_LIMITED_API
+#ifndef Py_TRACEMALLOC_H
+#define Py_TRACEMALLOC_H
+
+/* Track an allocated memory block in the tracemalloc module.
+   Return 0 on success, return -1 on error (failed to allocate memory to store
+   the trace).
+
+   Return -2 if tracemalloc is disabled.
+
+   If memory block is already tracked, update the existing trace. */
+PyAPI_FUNC(int) PyTraceMalloc_Track(
+    unsigned int domain,
+    uintptr_t ptr,
+    size_t size);
+
+/* Untrack an allocated memory block in the tracemalloc module.
+   Do nothing if the block was not tracked.
+
+   Return -2 if tracemalloc is disabled, otherwise return 0. */
+PyAPI_FUNC(int) PyTraceMalloc_Untrack(
+    unsigned int domain,
+    uintptr_t ptr);
+
+#endif  // !Py_TRACEMALLOC_H
+#endif  // !Py_LIMITED_API

Include/internal/pycore_tracemalloc.h

@@ -117,6 +117,51 @@ struct _tracemalloc_runtime_state {
     }
 
 
+/* Get the traceback where a memory block was allocated.
+
+   Return a tuple of (filename: str, lineno: int) tuples.
+
+   Return None if the tracemalloc module is disabled or if the memory block
+   is not tracked by tracemalloc.
+
+   Raise an exception and return NULL on error. */
+PyAPI_FUNC(PyObject*) _PyTraceMalloc_GetTraceback(
+    unsigned int domain,
+    uintptr_t ptr);
+
+/* Return non-zero if tracemalloc is tracing */
+extern int _PyTraceMalloc_IsTracing(void);
+
+/* Clear the tracemalloc traces */
+extern void _PyTraceMalloc_ClearTraces(void);
+
+/* Clear the tracemalloc traces */
+extern PyObject* _PyTraceMalloc_GetTraces(void);
+
+/* Clear tracemalloc traceback for an object */
+extern PyObject* _PyTraceMalloc_GetObjectTraceback(PyObject *obj);
+
+/* Initialize tracemalloc */
+extern int _PyTraceMalloc_Init(void);
+
+/* Start tracemalloc */
+extern int _PyTraceMalloc_Start(int max_nframe);
+
+/* Stop tracemalloc */
+extern void _PyTraceMalloc_Stop(void);
+
+/* Get the tracemalloc traceback limit */
+extern int _PyTraceMalloc_GetTracebackLimit(void);
+
+/* Get the memory usage of tracemalloc in bytes */
+extern size_t _PyTraceMalloc_GetMemory(void);
+
+/* Get the current size and peak size of traced memory blocks as a 2-tuple */
+extern PyObject* _PyTraceMalloc_GetTracedMemory(void);
+
+/* Set the peak size of traced memory blocks to the current size */
+extern void _PyTraceMalloc_ResetPeak(void);
+
 #ifdef __cplusplus
 }
 #endif

Include/tracemalloc.h

@@ -11,8 +11,10 @@
 
 try:
     import _testcapi
+    import _testinternalcapi
 except ImportError:
     _testcapi = None
+    _testinternalcapi = None
 
 
 EMPTY_STRING_SIZE = sys.getsizeof(b'')
@@ -1008,7 +1010,7 @@ def tearDown(self):
         tracemalloc.stop()
 
     def get_traceback(self):
-        frames = _testcapi.tracemalloc_get_traceback(self.domain, self.ptr)
+        frames = _testinternalcapi._PyTraceMalloc_GetTraceback(self.domain, self.ptr)
         if frames is not None:
             return tracemalloc.Traceback(frames)
         else:

Lib/test/test_tracemalloc.py

@@ -1658,7 +1658,6 @@ PYTHON_HEADERS= \
 		$(srcdir)/Include/structseq.h \
 		$(srcdir)/Include/sysmodule.h \
 		$(srcdir)/Include/traceback.h \
-		$(srcdir)/Include/tracemalloc.h \
 		$(srcdir)/Include/tupleobject.h \
 		$(srcdir)/Include/unicodeobject.h \
 		$(srcdir)/Include/warnings.h \
@@ -1713,6 +1712,7 @@ PYTHON_HEADERS= \
 		$(srcdir)/Include/cpython/setobject.h \
 		$(srcdir)/Include/cpython/sysmodule.h \
 		$(srcdir)/Include/cpython/traceback.h \
+		$(srcdir)/Include/cpython/tracemalloc.h \
 		$(srcdir)/Include/cpython/tupleobject.h \
 		$(srcdir)/Include/cpython/unicodeobject.h \
 		$(srcdir)/Include/cpython/warnings.h \

Makefile.pre.in

@@ -655,23 +655,6 @@ tracemalloc_untrack(PyObject *self, PyObject *args)
     Py_RETURN_NONE;
 }
 
-static PyObject *
-tracemalloc_get_traceback(PyObject *self, PyObject *args)
-{
-    unsigned int domain;
-    PyObject *ptr_obj;
-
-    if (!PyArg_ParseTuple(args, "IO", &domain, &ptr_obj)) {
-        return NULL;
-    }
-    void *ptr = PyLong_AsVoidPtr(ptr_obj);
-    if (PyErr_Occurred()) {
-        return NULL;
-    }
-
-    return _PyTraceMalloc_GetTraceback(domain, (uintptr_t)ptr);
-}
-
 static PyMethodDef test_methods[] = {
     {"check_pyobject_forbidden_bytes_is_freed",
                             check_pyobject_forbidden_bytes_is_freed, METH_NOARGS},
@@ -697,7 +680,6 @@ static PyMethodDef test_methods[] = {
     // Tracemalloc tests
     {"tracemalloc_track",             tracemalloc_track,             METH_VARARGS},
     {"tracemalloc_untrack",           tracemalloc_untrack,           METH_VARARGS},
-    {"tracemalloc_get_traceback",     tracemalloc_get_traceback,     METH_VARARGS},
     {NULL},
 };
 

Modules/_testcapi/mem.c

@@ -1216,6 +1216,24 @@ test_pytime_object_to_timespec(PyObject *self, PyObject *args)
 }
 
 
+static PyObject *
+tracemalloc_get_traceback(PyObject *self, PyObject *args)
+{
+    unsigned int domain;
+    PyObject *ptr_obj;
+
+    if (!PyArg_ParseTuple(args, "IO", &domain, &ptr_obj)) {
+        return NULL;
+    }
+    void *ptr = PyLong_AsVoidPtr(ptr_obj);
+    if (PyErr_Occurred()) {
+        return NULL;
+    }
+
+    return _PyTraceMalloc_GetTraceback(domain, (uintptr_t)ptr);
+}
+
+
 static PyMethodDef module_functions[] = {
     {"get_configs", get_configs, METH_NOARGS},
     {"get_recursion_depth", get_recursion_depth, METH_NOARGS},
@@ -1250,7 +1268,6 @@ static PyMethodDef module_functions[] = {
     {"get_uop_optimizer", get_uop_optimizer, METH_NOARGS, NULL},
     {"pending_threadfunc", _PyCFunction_CAST(pending_threadfunc),
      METH_VARARGS | METH_KEYWORDS},
-//    {"pending_fd_identify", pending_fd_identify, METH_VARARGS, NULL},
     {"pending_identify", pending_identify, METH_VARARGS, NULL},
     {"_PyTime_AsMicroseconds",    test_PyTime_AsMicroseconds,     METH_VARARGS},
     {"_PyTime_AsMilliseconds",    test_PyTime_AsMilliseconds,     METH_VARARGS},
@@ -1266,6 +1283,7 @@ static PyMethodDef module_functions[] = {
     {"_PyTime_ObjectToTime_t",    test_pytime_object_to_time_t,   METH_VARARGS},
     {"_PyTime_ObjectToTimespec",  test_pytime_object_to_timespec, METH_VARARGS},
     {"_PyTime_ObjectToTimeval",   test_pytime_object_to_timeval,  METH_VARARGS},
+    {"_PyTraceMalloc_GetTraceback", tracemalloc_get_traceback, METH_VARARGS},
     {NULL, NULL} /* sentinel */
 };
 

Modules/_testinternalcapi.c

@@ -179,6 +179,7 @@
     <ClInclude Include="..\Include\cpython\setobject.h" />
     <ClInclude Include="..\Include\cpython\sysmodule.h" />
     <ClInclude Include="..\Include\cpython\traceback.h" />
+    <ClInclude Include="..\Include\cpython\tracemalloc.h" />
     <ClInclude Include="..\Include\cpython\tupleobject.h" />
     <ClInclude Include="..\Include\cpython\unicodeobject.h" />
     <ClInclude Include="..\Include\cpython\warnings.h" />
@@ -320,7 +321,6 @@
     <ClInclude Include="..\Include\symtable.h" />
     <ClInclude Include="..\Include\sysmodule.h" />
     <ClInclude Include="..\Include\traceback.h" />
-    <ClInclude Include="..\Include\tracemalloc.h" />
     <ClInclude Include="..\Include\tupleobject.h" />
     <ClInclude Include="..\Include\unicodeobject.h" />
     <ClInclude Include="..\Include\weakrefobject.h" />

PCbuild/pythoncore.vcxproj

@@ -219,9 +219,6 @@
     <ClInclude Include="..\Include\traceback.h">
       <Filter>Include</Filter>
     </ClInclude>
-    <ClInclude Include="..\Include\tracemalloc.h">
-      <Filter>Include</Filter>
-    </ClInclude>
     <ClInclude Include="..\Include\tupleobject.h">
       <Filter>Include</Filter>
     </ClInclude>
@@ -453,6 +450,9 @@
     <ClInclude Include="..\Include\cpython\traceback.h">
       <Filter>Include\cpython</Filter>
     </ClInclude>
+    <ClInclude Include="..\Include\cpython\tracemalloc.h">
+      <Filter>Include</Filter>
+    </ClInclude>
     <ClInclude Include="..\Include\cpython\frameobject.h">
       <Filter>Include\cpython</Filter>
     </ClInclude>