Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio diffusion: return the heap a finished image load freed to the OS (#16934)

Daniel Hana3ed62e105a7
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 9432744fd69..93b92d91db5 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -238,6 +238,7 @@ from .diffusion_memory import (
release_pinned_host_memory,
request_background_encoder_pins,
finish_encoder_pins_at_load,
+ trim_host_heap_after_load,
start_background_pins,
stop_background_pins,
refine_balanced_plan_for_components,
@@ -11442,6 +11443,8 @@ class DiffusionBackend:
plan.estimates,
)
finish_encoder_pins_at_load(getattr(state, "pipe", None), logger)
+ # after the pins: their pageable sources are freed by now
+ trim_host_heap_after_load(logger)
return self.status()
@staticmethod
diff --git a/studio/backend/core/inference/diffusion_memory.py b/studio/backend/core/inference/diffusion_memory.py
index 02b2cd592ff..e4b863353b4 100644
--- a/studio/backend/core/inference/diffusion_memory.py
+++ b/studio/backend/core/inference/diffusion_memory.py
@@ -1092,6 +1092,61 @@ def reclaim_host_memory(logger: Any = None) -> bool:
return False
+LOAD_HEAP_TRIM_ENV = "UNSLOTH_DIFFUSION_LOAD_HEAP_TRIM"
+_load_heap_trim_warning_logged = False
+
+
+def _rss_anon_mib() -> Optional[int]:
+ try:
+ with open("/proc/self/status", encoding = "utf-8") as status:
+ for line in status:
+ if line.startswith("RssAnon:"):
+ return int(line.split()[1]) >> 10
+ except Exception: # noqa: BLE001 - not Linux, or no procfs
+ return None
+ return None
+
+
+def trim_host_heap_after_load(logger: Any = None) -> bool:
+ """Return the heap a finished load freed to the OS; glibc otherwise keeps it (Qwen-Image-2.1, 8 GiB budget:
+ 0.65 GiB warm, 1.9 GiB on a first load). Live tensors and the pinned caches are untouched."""
+ if _env_off(LOAD_HEAP_TRIM_ENV):
+ return False
+ try:
+ reclaim = _resolve_host_memory_reclaimer()
+ if reclaim is None:
+ return False
+ import time
+
+ before = _rss_anon_mib()
+ began = time.perf_counter()
+ reclaim()
+ took = time.perf_counter() - began
+ after = _rss_anon_mib()
+ if logger is not None:
+ if before is not None and after is not None:
+ logger.info(
+ "diffusion.memory: returned %d MiB of freed heap to the OS after the load (%.0f ms)",
+ before - after,
+ took * 1000,
+ )
+ else:
+ logger.info(
+ "diffusion.memory: returned freed heap to the OS after the load (%.0f ms)",
+ took * 1000,
+ )
+ return True
+ except Exception as exc: # noqa: BLE001 - a trim never fails a load
+ global _load_heap_trim_warning_logged
+ if logger is not None and not _load_heap_trim_warning_logged:
+ _load_heap_trim_warning_logged = True
+ try:
+ logger.warning("diffusion.memory: heap trim after the load failed: %s", exc)
+ except Exception: # noqa: BLE001
+ pass
+ return False
+
+
def normalize_memory_mode(value: Optional[str]) -> Optional[str]:
"""Lower/strip a requested mode (accepting dashes); None passes through. Raises ValueError
for an unsupported mode so the route rejects it as a 4xx before any GPU work."""
diff --git a/studio/backend/tests/test_diffusion_load_heap_trim.py b/studio/backend/tests/test_diffusion_load_heap_trim.py
new file mode 100644
index 00000000000..143f1d4d513
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_load_heap_trim.py
@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The image load hands the heap it freed back to the OS (CPU only, no torch)."""
+
+from __future__ import annotations
+
+import ast
+import os
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+import core.inference.diffusion_memory as diffusion_memory
+import pytest
+
+BACKEND = Path(__file__).resolve().parents[1]
+
+
+class _Log:
+ def __init__(self):
+ self.infos, self.warnings = [], []
+
+ def info(self, msg, *args):
+ self.infos.append(msg % args)
+
+ def warning(self, msg, *args):
+ self.warnings.append(msg % args)
+
+
+def test_trim_calls_the_allocator_reclaimer_and_logs_it(monkeypatch):
+ calls = []
+ monkeypatch.delenv(diffusion_memory.LOAD_HEAP_TRIM_ENV, raising = False)
+ monkeypatch.setattr(
+ diffusion_memory, "_resolve_host_memory_reclaimer", lambda: lambda: calls.append(1)
+ )
+ log = _Log()
+ assert diffusion_memory.trim_host_heap_after_load(log) is True
+ assert calls == [1]
+ assert any("freed heap" in line for line in log.infos)
+ assert not log.warnings
+
+
[email protected]("value", ["0", "off", "false", "no", " OFF "])
+def test_kill_switch_skips_the_trim(monkeypatch, value):
+ monkeypatch.setenv(diffusion_memory.LOAD_HEAP_TRIM_ENV, value)
+ monkeypatch.setattr(
+ diffusion_memory,
+ "_resolve_host_memory_reclaimer",
+ lambda: pytest.fail("the kill switch must not reach the allocator"),
+ )
+ assert diffusion_memory.trim_host_heap_after_load(_Log()) is False
+
+
+def test_no_allocator_api_is_a_quiet_no_op(monkeypatch):
+ monkeypatch.delenv(diffusion_memory.LOAD_HEAP_TRIM_ENV, raising = False)
+ monkeypatch.setattr(diffusion_memory, "_resolve_host_memory_reclaimer", lambda: None)
+ log = _Log()
+ assert diffusion_memory.trim_host_heap_after_load(log) is False
+ assert not log.infos and not log.warnings
+
+
+def test_a_failing_reclaimer_never_fails_the_load(monkeypatch):
+ monkeypatch.delenv(diffusion_memory.LOAD_HEAP_TRIM_ENV, raising = False)
+
+ def boom():
+ raise OSError("_heapmin failed")
+
+ monkeypatch.setattr(diffusion_memory, "_resolve_host_memory_reclaimer", lambda: boom)
+ monkeypatch.setattr(diffusion_memory, "_load_heap_trim_warning_logged", False)
+ log = _Log()
+ assert diffusion_memory.trim_host_heap_after_load(log) is False
+ assert log.warnings and "_heapmin failed" in log.warnings[0]
+ # warned once per process, not once per load
+ assert diffusion_memory.trim_host_heap_after_load(log) is False
+ assert len(log.warnings) == 1
+ assert diffusion_memory.trim_host_heap_after_load(None) is False
+
+
+def test_load_pipeline_trims_after_the_load_time_pins():
+ """The trim runs once the load's pins are done (their pageable sources are freed by then), on the success path."""
+ tree = ast.parse((BACKEND / "core/inference/diffusion.py").read_text(encoding = "utf-8"))
+ load = next(
+ node
+ for node in ast.walk(tree)
+ if isinstance(node, ast.FunctionDef) and node.name == "load_pipeline"
+ )
+ calls = [
+ node.func.id
+ for node in ast.walk(load)
+ if isinstance(node, ast.Call) and isinstance(node.func, ast.Name)
+ ]
+ assert "trim_host_heap_after_load" in calls
+ lines = {
+ node.func.id: node.lineno
+ for node in ast.walk(load)
+ if isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Name)
+ and node.func.id in ("finish_encoder_pins_at_load", "trim_host_heap_after_load")
+ }
+ assert lines["finish_encoder_pins_at_load"] < lines["trim_host_heap_after_load"]
+ last = load.body[-1]
+ assert isinstance(last, ast.Return)
+ before_return = load.body[-2]
+ assert (
+ isinstance(before_return, ast.Expr)
+ and isinstance(before_return.value, ast.Call)
+ and getattr(before_return.value.func, "id", None) == "trim_host_heap_after_load"
+ )
+
+
[email protected](not sys.platform.startswith("linux"), reason = "reads RssAnon from procfs")
+def test_trim_returns_fragmented_free_heap_to_the_os():
+ """Real glibc: freed chunks between live ones stay in the heap until a trim."""
+ import ctypes
+
+ if not hasattr(ctypes.CDLL(None), "malloc_trim"):
+ pytest.skip(
+ reason = "musl and other libcs without malloc_trim: the resolver declines, nothing to trim"
+ )
+ script = textwrap.dedent(
+ """
+ import json, logging
+ import core.inference.diffusion_memory as dm
+
+ def rss_anon():
+ for line in open("/proc/self/status"):
+ if line.startswith("RssAnon:"):
+ return int(line.split()[1]) >> 10
+
+ chunks = [bytearray(b"x" * (64 << 10)) for _ in range(6000)] # ~375 MiB of 64 KiB heap chunks
+ keep = chunks[::8] # live chunks pin the heap, so free() alone cannot shrink it
+ del chunks
+ before = rss_anon()
+ ok = dm.trim_host_heap_after_load(logging.getLogger("t"))
+ after = rss_anon()
+ print(json.dumps({"ok": ok, "before": before, "after": after, "kept": len(keep)}))
+ """
+ )
+ env = {k: v for k, v in os.environ.items() if k != diffusion_memory.LOAD_HEAP_TRIM_ENV}
+ env["PYTHONPATH"] = str(BACKEND) + os.pathsep + env.get("PYTHONPATH", "")
+ env.pop("MALLOC_TRIM_THRESHOLD_", None)
+ out = subprocess.run(
+ [sys.executable, "-c", script],
+ capture_output = True,
+ text = True,
+ cwd = str(BACKEND),
+ env = env,
+ timeout = 120,
+ )
+ assert out.returncode == 0, out.stderr[-2000:]
+ import json
+
+ res = json.loads(out.stdout.strip().splitlines()[-1])
+ assert res["ok"] is True
+ assert res["before"] - res["after"] >= 200, res