Optimize FFI Handle Disposal for Immediate Rust-Side Memory Release #524
Description
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 - f113704