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: pin the up-front slabs in registered host memory (faster load, same bytes) (#15562)

Daniel Han86f8bd2d8aad
diff --git a/studio/backend/core/inference/diffusion_memory.py b/studio/backend/core/inference/diffusion_memory.py
index fca4c070cec..78a2629e41d 100644
--- a/studio/backend/core/inference/diffusion_memory.py
+++ b/studio/backend/core/inference/diffusion_memory.py
@@ -6490,6 +6490,30 @@ class _RegisteredHostBuffer:
pass
+# "0" restores torch's pinned allocator for up-front pinned slabs.
+REGISTERED_SLAB_ENV = "UNSLOTH_DIFFUSION_REGISTERED_SLABS"
+
+
+def registered_pinned_empty(nbytes: int) -> Optional[Any]:
+ """Page-locked uint8 host tensor in registered memory, or None (use torch's pinned allocator).
+ Torch's allocator faults pages on one thread (~18 s for MiniMax-H3); ``zero_`` here faults them in parallel."""
+ if (os.environ.get(REGISTERED_SLAB_ENV) or "").strip().lower() in ("0", "off", "false", "no"):
+ return None
+ if int(nbytes) <= 0 or not _fast_pin_supported():
+ return None
+ import numpy as np
+ import torch
+
+ try:
+ holder = _RegisteredHostBuffer(int(nbytes))
+ buf = torch.from_numpy(np.asarray(holder))
+ buf.zero_()
+ holder.register()
+ except Exception: # noqa: BLE001
+ return None
+ return buf
+
+
def registered_host_copy(src: Any) -> Any:
"""A contiguous copy of host tensor ``src`` in CUDA-registered (pinned) memory."""
import numpy as np
diff --git a/studio/backend/core/inference/diffusion_pinned_arena.py b/studio/backend/core/inference/diffusion_pinned_arena.py
index 6b744ff8718..18445c961b2 100644
--- a/studio/backend/core/inference/diffusion_pinned_arena.py
+++ b/studio/backend/core/inference/diffusion_pinned_arena.py
@@ -33,8 +33,14 @@ def pin_arena_enabled() -> bool:
def _alloc_slab(nbytes: int) -> Any:
- """One pinned slab. A power-of-two request, so torch's host allocator rounds nothing."""
+ """One pinned slab: registered memory, else a power-of-two torch pinned request (no rounding)."""
import torch
+
+ from .diffusion_memory import registered_pinned_empty
+
+ slab = registered_pinned_empty(nbytes)
+ if slab is not None:
+ return slab
return torch.empty(nbytes, dtype = torch.uint8, pin_memory = True)
diff --git a/studio/backend/core/inference/video_minimax_h3_te.py b/studio/backend/core/inference/video_minimax_h3_te.py
index 20bbe2028ff..64374a44166 100644
--- a/studio/backend/core/inference/video_minimax_h3_te.py
+++ b/studio/backend/core/inference/video_minimax_h3_te.py
@@ -465,6 +465,17 @@ def _round_up(value: int, multiple: int) -> int:
return (value + multiple - 1) // multiple * multiple
+def _pinned_arena(size: int) -> Any:
+ import torch
+
+ from .diffusion_memory import registered_pinned_empty
+
+ arena = registered_pinned_empty(size)
+ if arena is not None:
+ return arena
+ return torch.empty(size, dtype = torch.uint8, pin_memory = True)
+
+
def pin_module_in_place(
module: Any,
*,
@@ -500,11 +511,7 @@ def pin_module_in_place(
slot = next((a for a in arenas if a[0].numel() - a[1] >= need), None)
if slot is None:
size = max(int(arena_bytes), 1 << (need - 1).bit_length())
- arena = (
- _arena_factory(size)
- if _arena_factory is not None
- else torch.empty(size, dtype = torch.uint8, pin_memory = True)
- )
+ arena = _arena_factory(size) if _arena_factory is not None else _pinned_arena(size)
slot = [arena, 0]
arenas.append(slot)
offset = slot[1]
diff --git a/studio/backend/tests/test_diffusion_registered_slabs.py b/studio/backend/tests/test_diffusion_registered_slabs.py
new file mode 100644
index 00000000000..4570d75f9b4
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_registered_slabs.py
@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Up-front pinned slabs come from registered host memory; ``UNSLOTH_DIFFUSION_REGISTERED_SLABS=0`` restores torch's."""
+
+import numpy as np
+import pytest
+import torch
+
+from core.inference import diffusion_memory as dm
+from core.inference import diffusion_pinned_arena as arena_mod
+
+
+class _FakeHolder:
+ """CPU-only stand-in for ``_RegisteredHostBuffer``."""
+
+ made: list = []
+
+ def __init__(self, nbytes):
+ self._arr = np.full(int(nbytes), 7, dtype = np.uint8) # dirty, so the zero fill is observable
+ self.__array_interface__ = self._arr.__array_interface__
+ self.registered_after_zero = None
+ _FakeHolder.made.append(self)
+
+ def register(self):
+ self.registered_after_zero = bool((self._arr == 0).all())
+
+
+def fake_registered(monkeypatch):
+ _FakeHolder.made = []
+ monkeypatch.delenv(dm.REGISTERED_SLAB_ENV, raising = False)
+ monkeypatch.setattr(dm, "_fast_pin_supported", lambda: True)
+ monkeypatch.setattr(dm, "_RegisteredHostBuffer", _FakeHolder)
+ return _FakeHolder.made
+
+
+def test_registered_pinned_empty_zero_fills_before_registering(fake_registered):
+ buf = dm.registered_pinned_empty(4096)
+ assert buf is not None and buf.dtype == torch.uint8 and buf.numel() == 4096
+ assert len(fake_registered) == 1 and fake_registered[0].registered_after_zero is True
+ assert int(buf.sum()) == 0
+
+
[email protected]("value", ["0", "off", "false", "no"])
+def test_kill_switch_restores_the_pinned_allocator(fake_registered, monkeypatch, value):
+ monkeypatch.setenv(dm.REGISTERED_SLAB_ENV, value)
+ assert dm.registered_pinned_empty(4096) is None
+ assert fake_registered == []
+
+
+def test_unsupported_host_or_refused_registration_falls_back(fake_registered, monkeypatch):
+ monkeypatch.setattr(dm, "_fast_pin_supported", lambda: False)
+ assert dm.registered_pinned_empty(4096) is None
+ monkeypatch.setattr(dm, "_fast_pin_supported", lambda: True)
+
+ def refuse(self):
+ raise RuntimeError("cudaHostRegister failed")
+
+ monkeypatch.setattr(_FakeHolder, "register", refuse)
+ assert dm.registered_pinned_empty(4096) is None
+ assert dm.registered_pinned_empty(0) is None
+
+
+def test_arena_slabs_come_from_registered_memory(fake_registered):
+ weights = [
+ torch.randn(64, 32),
+ torch.arange(100, dtype = torch.int8),
+ torch.randn(7, dtype = torch.float16),
+ ]
+ arena = arena_mod.PinnedArena(slab_bytes = 1 << 14)
+ copies = [arena.pin(w) for w in weights]
+ assert len(fake_registered) == len(arena._slabs) >= 1
+ slab_ptrs = {s.untyped_storage().data_ptr() for s, _ in arena._slabs}
+ for w, c in zip(weights, copies):
+ assert torch.equal(w, c)
+ assert c.untyped_storage().data_ptr() in slab_ptrs
+
+
+def test_arena_uses_torch_pinned_allocator_when_registration_is_off(fake_registered, monkeypatch):
+ monkeypatch.setenv(dm.REGISTERED_SLAB_ENV, "0")
+ seen = []
+
+ def fake_empty(
+ n,
+ dtype = None,
+ pin_memory = False,
+ ):
+ seen.append(pin_memory)
+ return torch.zeros(n, dtype = dtype)
+
+ monkeypatch.setattr(torch, "empty", fake_empty)
+ arena_mod._alloc_slab(1 << 12)
+ assert seen == [True] and fake_registered == []
+
+
+def test_h3_conditioner_pin_in_place_uses_registered_arenas(fake_registered):
+ from core.inference.video_minimax_h3_te import pin_module_in_place
+
+ m = torch.nn.Sequential(torch.nn.Linear(16, 32), torch.nn.Linear(32, 8))
+ m.register_buffer("q", torch.arange(64, dtype = torch.int8).view(8, 8))
+ expect = {k: v.detach().clone() for k, v in m.state_dict().items()}
+ pinned = pin_module_in_place(m, arena_bytes = 1 << 14)
+ assert pinned == sum(t.numel() * t.element_size() for t in expect.values())
+ assert len(fake_registered) == 1
+ for k, v in m.state_dict().items():
+ assert torch.equal(v, expect[k]), k
+
+
[email protected](not torch.cuda.is_available(), reason = "needs CUDA")
+def test_real_registered_slab_is_pinned_and_uploads_exactly(monkeypatch):
+ monkeypatch.delenv(dm.REGISTERED_SLAB_ENV, raising = False)
+ if not dm._fast_pin_supported():
+ pytest.skip("registered pinning unsupported on this host")
+ buf = dm.registered_pinned_empty(1 << 20)
+ assert buf is not None and buf.is_pinned()
+ src = torch.randint(0, 255, (1 << 20,), dtype = torch.uint8)
+ buf.copy_(src)
+ dev = buf.to("cuda", non_blocking = True)
+ torch.cuda.synchronize()
+ assert torch.equal(dev.cpu(), src)
diff --git a/studio/backend/tests/test_integrated_gpu_no_host_pin.py b/studio/backend/tests/test_integrated_gpu_no_host_pin.py
index 3761be30042..e2ae3057961 100644
--- a/studio/backend/tests/test_integrated_gpu_no_host_pin.py
+++ b/studio/backend/tests/test_integrated_gpu_no_host_pin.py
@@ -464,6 +464,10 @@ _REACHED_THROUGH_A_GATE = {
"core/inference/video_minimax_h3_te.py",
"pin_module_in_place",
): "h3_te_pin_allowed / stream_h3_text_encoder",
+ (
+ "core/inference/video_minimax_h3_te.py",
+ "_pinned_arena",
+ ): "pin_module_in_place",
(
"core/inference/video_minimax_h3_residency.py",
"_pin_host_tensor",