Add comprehensive documentation for the DisTorch selective model unload
solution that addresses Python garbage collection issues. The document
details:
- Problem: Models with keep_loaded=False were being prematurely garbage
collected despite being added to current_loaded_models list
- Root cause: Reassigning current_loaded_models created the only strong
reference, making models vulnerable to GC between assignment and next
access
- Solution: Global GC anchor set (_MGPU_RETENTION_ANCHORS) maintains
strong references to ModelPatcher objects that should survive cleanup
- Implementation: Early delegation check, anchor protection during
categorization, and explicit lifecycle management
- Testing results: Confirms Flux unloads while VAE/CLIP remain protected
This solution ensures DisTorch models can selectively unload while
keeping VAE and CLIP models loaded, preventing memory management race
conditions with Python's garbage collector.
John Pollock
bde51c6236