Walkthrough

This PR introduces garbage collection cycle detection and breaking mechanisms for RustPython's VM. It adds a clear traversal hook to extract child references from objects, implements GC bit tracking operations on PyObject, integrates automatic object tracking during creation, and modifies deallocation to run tp_clear before freeing memory.

Changes

Sequence Diagram

sequenceDiagram
    participant Code as Client Code
    participant PyRef as PyRef Creation
    participant PyObj as PyObject
    participant GCState as GC State
    participant Dealloc as Deallocation
    
    Code->>PyRef: new_ref(payload, type, dict)
    PyRef->>PyObj: Create with payload
    PyRef->>GCState: Check traversal capability
    alt Has Traverse + Dict/HeapType
        PyRef->>GCState: track_object()
        GCState->>PyObj: set_gc_tracked()
        PyObj->>PyObj: Mark GC bit
    end
    
    Note over GCState: GC Cycle Detection Triggered
    GCState->>PyObj: Invoke clear callback
    PyObj->>PyObj: Call tp_clear (via try_clear_obj)
    PyObj-->>GCState: Return child references
    GCState->>GCState: Process references for cycles
    
    Code->>Dealloc: Object deallocation
    Dealloc->>PyObj: default_dealloc()
    Dealloc->>PyObj: tp_clear() if not cleared
    Dealloc->>PyObj: Extract collected edges
    Dealloc->>Dealloc: Free memory

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• gc module internal structure and API #6910: Directly modifies the same GC subsystem including gc_state::track_object, PyObject GC bits, and vtable traversal/clear hooks.
• Improve object traversal for heap types and mro #6976: Alters PyType's traversal behavior to complement the new clear hook mechanism introduced here.
• impl gc finialized #6689: Modifies PyObject GC-bit management and related operations that are extended in this PR.

Suggested reviewers

• ShaharNaveh

Poem

🐰 A rabbit's ode to cycles broke,
With clear hooks and GC strokes,
Bits are tracked with care so fine,
Memory freed in perfect line,
No more cycles to provoke! ✨

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

• 📝 Generate docstrings

• X
• Mastodon
• Reddit
• LinkedIn