Add Python object reference tracking

This feature adds the capability to track Python objects throughout
their lifecycle in memray. The implementation introduces a reference
tracking system that records PyObject creation and destruction events,
storing them as TrackedObject records in the memray capture file with
associated stack traces. The Tracker class now accepts a
reference_tracking flag to enable this functionality and provides a
get_surviving_objects() method to retrieve live objects at the end of
tracking.

Object tracking works across threads and supports native, Python, and
hybrid stack traces, providing insights into Python object
lifetimes. This enhancement extends memray beyond memory allocation
tracking to give developers a powerful tool for understanding object
lifecycles and identifying potential reference leaks.

With this addition, memray can now correlate memory allocations with the
Python objects that trigger them, enabling more precise debugging of
memory usage patterns. The feature is particularly useful for
identifying objects that persist longer than expected or detecting
unexpected object creation patterns. By tracking both memory allocations
and object references, memray provides a more complete picture of a
program's memory behavior, helping developers optimize memory usage and
resolve leaks more effectively.

This implementation leverages the new Python reference tracing API that
was introduced in CPython 3.13.

Signed-off-by: Pablo Galindo <[email protected]>

Author: pablogsal

news/752.feature.rst

@@ -0,0 +1 @@
+Add a mode that can be used in Python 3.13.3 and newer where Memray will track Python object creation and destruction events, which can be used to find leaked objects (ones that were created during a tracking session and not destroyed before the end of that tracking session).

src/memray/_memray.pyi

@@ -67,6 +67,35 @@ class AllocationRecord:
     def __lt__(self, other: Any) -> Any: ...
     def __ne__(self, other: Any) -> Any: ...
 
+class TrackedObjectRecord:
+    @property
+    def tid(self) -> int: ...
+    @property
+    def address(self) -> int: ...
+    @property
+    def is_created(self) -> bool: ...
+    @property
+    def frame_index(self) -> int: ...
+    @property
+    def native_frame_id(self) -> int: ...
+    @property
+    def native_segment_generation(self) -> int: ...
+    def toPythonObject(self) -> Any: ...
+    def hybrid_stack_trace(
+        self,
+        max_stacks: Optional[int] = None,
+    ) -> List[Union[PythonStackElement, NativeStackElement]]: ...
+    def native_stack_trace(
+        self, max_stacks: Optional[int] = None
+    ) -> List[NativeStackElement]: ...
+    def stack_trace(
+        self, max_stacks: Optional[int] = None
+    ) -> List[PythonStackElement]: ...
+    def __eq__(self, other: Any) -> Any: ...
+    def __hash__(self) -> Any: ...
+    def __repr__(self) -> str: ...
+    def __str__(self) -> str: ...
+
 class Interval:
     def __init__(
         self,
@@ -171,6 +200,9 @@ class FileReader:
     @property
     def closed(self) -> bool: ...
     def close(self) -> None: ...
+    def get_tracked_objects(
+        self, filter_objs: Optional[Iterable[Any]] = None
+    ) -> Iterable[TrackedObjectRecord]: ...
 
 def compute_statistics(
     file_name: Union[str, Path],
@@ -214,6 +246,7 @@ class Tracker:
         follow_fork: bool = ...,
         trace_python_allocators: bool = ...,
         file_format: FileFormat = ...,
+        reference_tracking: bool = ...,
     ) -> None: ...
     @overload
     def __init__(
@@ -225,6 +258,7 @@ class Tracker:
         follow_fork: bool = ...,
         trace_python_allocators: bool = ...,
         file_format: FileFormat = ...,
+        reference_tracking: bool = ...,
     ) -> None: ...
     def __enter__(self) -> Any: ...
     def __exit__(