livekit
Optimize FFI Handle Disposal for Immediate Rust-Side Memory Release
Issue Description Currently, when creating Python objects from Rust-owned buffers via FFI, the FfiHandle instances are created but not explicitly disposed. This leads to delayed memory deallocation on the Rust side, as the handles rely on Python's garbage collector for cleanup. This can result in unnecessary memory retention, especially in high-throughput scenarios with frequent frame processing.
Why This is an Improvement Immediate Resource Release: Explicit disposal of FfiHandle instances ensures that Rust-side memory is freed immediately after Python copies the data, rather than waiting for garbage collection Predictable Memory Usage: Eliminates uncertainty around when memory will be released, making memory usage more predictable Reduced Peak Memory: Prevents accumulation of unreleased Rust buffers during intensive processing periods Better Performance: Avoids potential memory pressure that could trigger garbage collection at inconvenient times Changes Required The following files need modifications to ensure immediate disposal of FFI handles:
livekit/rtc/audio_frame.py Line 95: Change FfiHandle(owned_info.handle.id) to FfiHandle(owned_info.handle.id).dispose() This ensures the Rust-side audio buffer is freed immediately after creating the Python AudioFrame livekit/rtc/video_frame.py Line 105: Change FfiHandle(owned_info.handle.id) to FfiHandle(owned_info.handle.id).dispose() This ensures the Rust-side video buffer is freed immediately after creating the Python VideoFrame Technical Details The changes leverage the existing FfiHandle.dispose() method which:
Calls the Rust FFI to immediately deallocate the buffer Prevents the handle from waiting for Python's garbage collector Maintains the same API while improving resource management Testing The existing test suite in tests/test_memory_monitoring.py already includes memory profiling with tracemalloc and object counting, which will help validate that:
Memory usage remains stable during extended recording sessions No memory leaks occur from improper handle disposal Peak memory usage is reduced compared to the previous implementation Migration Notes This is a breaking change for any code that was relying on the delayed disposal behavior. However, such reliance would be incorrect usage of the FFI handles. The change is safe for all existing code as it only affects internal memory management timing.
Change has been implemented and tested in a fork of this project - https://github.com/livekit/python-sdks/commit/f11370459098fbf058e59ceac00f40ff6d49932a
