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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Linux PDEATHSIG cases spawn real processes; the Windows Job Object path uses a mocked kernel32."""
from __future__ import annotations
import multiprocessing.process
import os
import signal
import subprocess
import sys
import time
from pathlib import Path
import pytest
_BACKEND = Path(__file__).resolve().parent.parent
if str(_BACKEND) not in sys.path:
sys.path.insert(0, str(_BACKEND))
import utils.process_lifetime as pl # noqa: E402
IS_POSIX = os.name == "posix"
IS_LINUX = sys.platform.startswith("linux")
@pytest.fixture(autouse = True)
def _reset_module_state():
pl._tracked_pids.clear()
pl._win_job_handle = None
pl._initialized = False
yield
pl._tracked_pids.clear()
pl._win_job_handle = None
pl._initialized = False
def _alive(pid: int) -> bool:
if sys.platform == "win32":
return _win_alive(pid)
try:
os.kill(pid, 0) # POSIX existence probe (on Windows this would terminate it)
return True
except OSError:
return False
def _win_alive(pid: int) -> bool:
import ctypes
PROCESS_QUERY_LIMITED_INFORMATION, STILL_ACTIVE = 0x1000, 259
kernel32 = ctypes.windll.kernel32
handle = kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
if not handle:
return False
code = ctypes.c_ulong()
kernel32.GetExitCodeProcess(handle, ctypes.byref(code))
kernel32.CloseHandle(handle)
return code.value == STILL_ACTIVE
def _wait_dead(pid: int, timeout: float) -> bool:
end = time.time() + timeout
while time.time() < end:
if not _alive(pid):
return True
time.sleep(0.05)
return not _alive(pid)
def test_initialize_idempotent_and_noop_on_posix():
pl.initialize_parent_lifetime()
pl.initialize_parent_lifetime()
if IS_POSIX:
assert pl._win_job_handle is None
def test_adopt_pid_tolerates_none_and_dead_pid():
pl.adopt_pid(None)
pl.adopt_pid(2**31 - 1)
assert None not in pl._tracked_pids
def test_child_popen_kwargs_linux_vs_other(monkeypatch):
monkeypatch.setattr(pl, "_is_linux", lambda: True)
assert "preexec_fn" in pl.child_popen_kwargs()
monkeypatch.setattr(pl, "_is_linux", lambda: False)
assert pl.child_popen_kwargs() == {}
def test_compose_preexec_runs_pdeathsig_then_existing(monkeypatch):
calls = []
monkeypatch.setattr(pl, "_is_linux", lambda: True)
monkeypatch.setattr(pl, "_pdeathsig_preexec", lambda owner: calls.append(("death", owner)))
pl.compose_preexec(lambda: calls.append("existing"), 4242)()
assert calls == [("death", 4242), "existing"] # ordering matters for sandbox hooks
def test_compose_preexec_passthrough_off_linux(monkeypatch):
monkeypatch.setattr(pl, "_is_linux", lambda: False)
sentinel = lambda: None # noqa: E731
assert pl.compose_preexec(sentinel) is sentinel
assert pl.compose_preexec(None) is None
def test_child_popen_kwargs_binds_the_spawning_pid(monkeypatch):
# Compare against the forking pid, so a healthy child of a pid-1 parent is not an orphan.
seen = []
monkeypatch.setattr(pl, "_is_linux", lambda: True)
monkeypatch.setattr(pl, "_pdeathsig_preexec", lambda owner: seen.append(owner))
pl.child_popen_kwargs()["preexec_fn"]()
assert seen == [os.getpid()]
class _ExitCalled(BaseException):
"""Stands in for os._exit, which a test cannot survive. A BaseException so
the hook's own `except Exception` does not swallow it."""
def _run_preexec(monkeypatch, *, owner_pid, getppid):
import ctypes
class _Libc:
def prctl(self, *args):
return 0
def _no_exit(code):
raise _ExitCalled(code)
monkeypatch.setattr(ctypes, "CDLL", lambda *a, **k: _Libc())
monkeypatch.setattr(pl.os, "getppid", lambda: getppid)
monkeypatch.setattr(pl.os, "_exit", _no_exit)
pl._pdeathsig_preexec(owner_pid)
def test_pdeathsig_keeps_child_whose_parent_is_pid_1(monkeypatch):
# As a container entrypoint Unsloth is pid 1, so healthy children see getppid() == 1.
_run_preexec(monkeypatch, owner_pid = 1, getppid = 1)
def test_pdeathsig_exits_when_reparented_away_from_the_owner(monkeypatch):
with pytest.raises(_ExitCalled):
_run_preexec(monkeypatch, owner_pid = 4242, getppid = 1)
def _bind_with_parent(monkeypatch, parent):
import multiprocessing
seen, exited = [], []
monkeypatch.setattr(pl, "_is_linux", lambda: True)
monkeypatch.setattr(pl, "_pdeathsig_preexec", lambda owner: seen.append(owner))
monkeypatch.setattr(pl.os, "_exit", lambda code: exited.append(code))
monkeypatch.setattr(multiprocessing, "parent_process", lambda: parent)
pl.bind_current_process_to_parent_lifetime()
return seen, exited
def test_bind_keeps_a_worker_whose_creator_is_alive(monkeypatch):
# Decided from the creator's sentinel: under forkserver the kernel parent is the fork server.
seen, exited = _bind_with_parent(monkeypatch, _FakeParent(4242, alive = True))
assert seen == [os.getppid()]
assert exited == []
def test_bind_exits_when_the_creator_is_already_gone(monkeypatch):
seen, exited = _bind_with_parent(monkeypatch, _FakeParent(4242, alive = False))
assert seen == [os.getppid()]
assert exited == [1]
def test_bind_only_arms_pdeathsig_outside_a_multiprocessing_worker(monkeypatch):
seen, exited = _bind_with_parent(monkeypatch, None)
assert seen == [os.getppid()]
assert exited == []
def test_bind_keeps_a_non_worker_whose_parent_is_pid_1(monkeypatch):
import ctypes
import multiprocessing
exited = []
monkeypatch.setattr(pl, "_is_linux", lambda: True)
monkeypatch.setattr(ctypes, "CDLL", lambda *a, **k: type("L", (), {"prctl": lambda *_: 0})())
monkeypatch.setattr(pl.os, "getppid", lambda: 1)
monkeypatch.setattr(pl.os, "_exit", lambda code: exited.append(code))
monkeypatch.setattr(multiprocessing, "parent_process", lambda: None)
pl.bind_current_process_to_parent_lifetime()
assert exited == []
class _FakeParent:
def __init__(self, pid, alive):
self.pid, self._alive = pid, alive
def is_alive(self):
return self._alive
@pytest.mark.skipif(not IS_LINUX, reason = "PR_SET_PDEATHSIG is Linux-only")
def test_pdeathsig_child_dies_when_parent_sigkilled(tmp_path):
mid = tmp_path / "mid.py"
mid.write_text(
"import sys, subprocess, time\n"
f"sys.path.insert(0, {str(_BACKEND)!r})\n"
"from utils.process_lifetime import child_popen_kwargs\n"
"p = subprocess.Popen(['sleep', '300'], **child_popen_kwargs())\n"
"print(p.pid, flush = True)\n"
"time.sleep(300)\n"
)
proc = subprocess.Popen([sys.executable, str(mid)], stdout = subprocess.PIPE, text = True)
try:
sleeper_pid = int(proc.stdout.readline().strip())
assert _alive(sleeper_pid)
proc.kill()
proc.wait(timeout = 5)
assert _wait_dead(sleeper_pid, 5.0), "child orphaned after parent SIGKILL"
finally:
proc.kill()
def _fake_pyav_frame(monkeypatch):
import threading
import types
frame = types.ModuleType("av.video.frame")
frame._thread_local = threading.local()
monkeypatch.setitem(sys.modules, "av.video.frame", frame)
return frame
def test_a_fork_frees_other_threads_cached_scalers_in_the_parent(monkeypatch):
"""PyAV 19+ caches a scaler per thread; one freed in a fork child waits on FFmpeg threads it does not have."""
import threading
frame = _fake_pyav_frame(monkeypatch)
freed_in = []
class Scaler:
def __del__(self):
freed_in.append(os.getpid())
cached, stop = threading.Event(), threading.Event()
def video_worker():
frame._thread_local.reformatter = Scaler()
cached.set()
stop.wait() # an idle pool thread keeps its cache
worker = threading.Thread(target = video_worker, daemon = True)
worker.start()
try:
assert cached.wait(5), "the worker never cached its scaler"
pl._suspend_native_caches()
# Freed now, in this process, though the thread that cached it is still alive.
assert freed_in == [os.getpid()]
finally:
pl._resume_native_caches_in_parent()
stop.set()
worker.join(5)
assert type(frame._thread_local) is threading.local
def test_nothing_is_cached_into_a_fork_while_the_old_scalers_are_freed(monkeypatch):
"""Freeing a scaler releases the GIL, so another thread can reformat (and cache) before the fork happens."""
frame = _fake_pyav_frame(monkeypatch)
class Scaler:
def __del__(self):
# What a reformat on another thread does while this one is in sws_freeContext.
frame._thread_local.reformatter = "cached during the fork"
frame._thread_local.reformatter = Scaler()
try:
pl._suspend_native_caches()
assert getattr(frame._thread_local, "reformatter", None) is None
finally:
pl._resume_native_caches_in_parent()
frame._thread_local.reformatter = "cached after the fork"
assert frame._thread_local.reformatter == "cached after the fork"
def test_overlapping_forks_keep_caching_off_until_the_last_returns(monkeypatch):
import threading
frame = _fake_pyav_frame(monkeypatch)
pl._suspend_native_caches()
pl._suspend_native_caches() # a second thread forking before the first one's fork returned
pl._resume_native_caches_in_parent()
assert type(frame._thread_local) is pl._UncachedReformatters
pl._resume_native_caches_in_parent()
assert type(frame._thread_local) is threading.local
pl._resume_native_caches_in_parent() # an unpaired resume cannot go negative
pl._suspend_native_caches()
assert type(frame._thread_local) is pl._UncachedReformatters
pl._resume_native_caches_in_parent()
def test_the_hooks_are_registered_at_import(tmp_path):
"""At import, so forks that bring their own preexec_fn or call os.fork directly are covered too."""
if not hasattr(os, "register_at_fork"):
pytest.skip("os.register_at_fork is POSIX-only")
probe = (
"import os, sys\n"
"registered = []\n"
"os.register_at_fork = lambda **kw: registered.append(sorted((k, v.__name__) for k, v in kw.items()))\n"
f"sys.path.insert(0, {str(_BACKEND)!r})\n"
"import utils.process_lifetime\n"
"print(registered)\n"
)
out = subprocess.run([sys.executable, "-c", probe], capture_output = True, text = True, timeout = 60)
ours = [
("after_in_child", "_resume_native_caches_in_child"),
("after_in_parent", "_resume_native_caches_in_parent"),
("before", "_suspend_native_caches"),
]
assert str(ours) in out.stdout, out.stdout + out.stderr
_SPAWN_AFTER_REFORMAT = """
import os, signal, subprocess, sys, threading
sys.path.insert(0, {backend!r})
import av, numpy as np
from utils.process_lifetime import child_popen_kwargs, spawn_on_lifetime_thread
ready, stop, errors = threading.Event(), threading.Event(), []
def video_worker():
try:
frame = av.VideoFrame.from_ndarray(np.zeros((720, 1280, 3), dtype = np.uint8), format = "rgb24")
frame.reformat(format = "yuv420p", width = 640, height = 360)
except Exception as exc:
errors.append(repr(exc))
ready.set()
stop.wait()
def fork_once(how):
if how == "spawner":
return spawn_on_lifetime_thread(lambda: subprocess.Popen(["true"], **child_popen_kwargs())).wait()
if how == "own_preexec":
return subprocess.Popen(["true"], preexec_fn = lambda: None).wait()
pid = os.fork()
if pid == 0:
os._exit(0)
return os.waitpid(pid, 0)[1]
threading.Thread(target = video_worker, daemon = True).start()
if not ready.wait(30) or errors:
print("worker failed", errors, flush = True)
os._exit(4)
box = []
t = threading.Thread(target = lambda: box.append(fork_once({how!r})), daemon = True)
t.start()
t.join(30)
if t.is_alive():
print("hung", flush = True)
# The stuck child never reached PDEATHSIG, so it would outlive this script.
for tid in os.listdir("/proc/self/task"):
try:
with open(f"/proc/self/task/{{tid}}/children") as handle:
kids = handle.read().split()
except OSError:
continue
for kid in kids:
try:
os.kill(int(kid), signal.SIGKILL)
except ProcessLookupError:
pass
os._exit(3)
print("exit", box[0], flush = True)
"""
@pytest.mark.skipif(not IS_LINUX, reason = "the fork-then-Python spawn paths are Linux-only here")
@pytest.mark.parametrize("how", ["spawner", "own_preexec", "os_fork"])
def test_a_fork_after_a_video_reformat_still_completes(tmp_path, how):
"""A pool thread that reformatted one frame used to hang the next fork whose child runs Python before exec."""
pytest.importorskip("av")
pytest.importorskip("numpy")
script = tmp_path / "fork_after_reformat.py"
script.write_text(_SPAWN_AFTER_REFORMAT.format(backend = str(_BACKEND), how = how))
# The hang is in a child that never execs, so bound the whole scenario from outside.
result = subprocess.run(
[sys.executable, str(script)], capture_output = True, text = True, timeout = 120
)
assert result.stdout.strip() == "exit 0", result.stdout + result.stderr
@pytest.mark.skipif(sys.platform != "win32", reason = "Windows Job Object")
def test_windows_job_kills_child_when_parent_dies(tmp_path):
mid = tmp_path / "mid.py"
mid.write_text(
"import sys, subprocess, time\n"
f"sys.path.insert(0, {str(_BACKEND)!r})\n"
"import utils.process_lifetime as pl\n"
"pl.initialize_parent_lifetime()\n"
"p = subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(300)'])\n"
"print(p.pid, int(pl._win_job_handle is not None), flush = True)\n"
"time.sleep(300)\n"
)
proc = subprocess.Popen([sys.executable, str(mid)], stdout = subprocess.PIPE, text = True)
try:
first = proc.stdout.readline().split()
child_pid, installed = int(first[0]), first[1] == "1"
assert installed, "Windows Job Object was not installed"
assert _alive(child_pid)
proc.kill()
proc.wait(timeout = 5)
assert _wait_dead(child_pid, 5.0), "child orphaned after parent killed"
finally:
proc.kill()
@pytest.mark.skipif(not IS_POSIX, reason = "POSIX process sweep")
def test_terminate_all_signals_tracked_and_is_idempotent():
p = subprocess.Popen(["sleep", "300"])
pl.adopt_pid(p.pid)
pl.terminate_all()
assert p.wait(timeout = 5) is not None
pl.terminate_all()
@pytest.mark.skipif(not IS_POSIX, reason = "POSIX process sweep")
def test_terminate_all_escalates_to_sigkill():
p = subprocess.Popen(
[
sys.executable,
"-c",
"import signal, time; signal.signal(signal.SIGTERM, signal.SIG_IGN); time.sleep(300)",
]
)
time.sleep(0.5)
pl.adopt_pid(p.pid)
pl.terminate_all(timeout = 0.3)
assert p.wait(timeout = 5) == -signal.SIGKILL
@pytest.mark.skipif(not IS_POSIX, reason = "POSIX process sweep")
def test_terminate_all_lets_cooperative_child_exit_cleanly(tmp_path):
marker = tmp_path / "clean.txt"
p = subprocess.Popen(
[
sys.executable,
"-c",
"import signal, sys, time\n"
f"def h(*a): open({str(marker)!r}, 'w').write('clean'); sys.exit(0)\n"
"signal.signal(signal.SIGTERM, h)\n"
"time.sleep(300)\n",
]
)
time.sleep(0.5)
pl.adopt_pid(p.pid)
pl.terminate_all(timeout = 3.0)
assert p.wait(timeout = 3) == 0
assert marker.read_text() == "clean"
def test_forget_pid_unregisters():
pl.adopt_pid(4242)
assert 4242 in pl._tracked_pids
pl.forget_pid(4242)
assert 4242 not in pl._tracked_pids
@pytest.mark.skipif(not IS_POSIX, reason = "POSIX process sweep")
def test_terminate_all_skips_recycled_pid(monkeypatch):
p = subprocess.Popen(["sleep", "300"])
pl.adopt_pid(p.pid)
monkeypatch.setattr(pl, "_pid_identity", lambda _pid: "DIFFERENT")
pl.terminate_all()
assert _alive(p.pid)
p.kill()
p.wait(timeout = 5)
@pytest.mark.skipif(not IS_LINUX, reason = "PR_SET_PDEATHSIG is Linux-only")
@pytest.mark.parametrize("lifetime_thread", [False, True])
def test_bind_kills_multiprocessing_child_on_parent_death(tmp_path, lifetime_thread):
# multiprocessing workers can't take a preexec_fn, so they bind via
# bind_current_process_to_parent_lifetime().
mid = tmp_path / "mid_mp.py"
mid.write_text(
"import sys, time, multiprocessing as mp\n"
f"sys.path.insert(0, {str(_BACKEND)!r})\n"
"from utils.process_lifetime import bind_current_process_to_parent_lifetime, spawn_on_lifetime_thread\n"
"def _child(ready):\n"
" bind_current_process_to_parent_lifetime()\n"
" ready.set()\n"
" time.sleep(300)\n"
"if __name__ == '__main__':\n"
" ctx = mp.get_context('spawn')\n"
" ready = ctx.Event()\n"
" p = ctx.Process(target = _child, args = (ready,), daemon = True)\n"
f" {'spawn_on_lifetime_thread(p.start)' if lifetime_thread else 'p.start()'}\n"
" assert ready.wait(10), 'child did not arm its parent-death signal'\n"
" print(p.pid, flush = True)\n"
" time.sleep(300)\n"
)
proc = subprocess.Popen([sys.executable, str(mid)], stdout = subprocess.PIPE, text = True)
try:
child_pid = int(proc.stdout.readline().strip())
assert _alive(child_pid)
proc.kill()
proc.wait(timeout = 5)
assert _wait_dead(child_pid, 5.0), "mp child orphaned after parent SIGKILL"
finally:
proc.kill()
class _Call:
def __init__(self, name, log, ret):
self.name, self.log, self.ret = name, log, ret
self.restype = self.argtypes = None
def __call__(self, *a, **k):
self.log.append(self.name)
return self.ret
class _FakeKernel32:
def __init__(
self,
log,
create_ret = 4321,
set_ret = 1,
assign_ret = 1,
):
self.CreateJobObjectW = _Call("create", log, create_ret)
self.SetInformationJobObject = _Call("set", log, set_ret)
self.AssignProcessToJobObject = _Call("assign", log, assign_ret)
self.GetCurrentProcess = _Call("getcur", log, -1)
self.CloseHandle = _Call("close", log, 1)
def _patch_windows(monkeypatch, fake):
import ctypes
monkeypatch.setattr(pl, "_is_windows", lambda: True)
monkeypatch.setattr(ctypes, "WinDLL", lambda *a, **k: fake, raising = False)
def test_windows_job_install_order(monkeypatch):
log: list[str] = []
_patch_windows(monkeypatch, _FakeKernel32(log))
pl._install_windows_job()
assert log.index("create") < log.index("set") < log.index("assign")
assert pl._win_job_handle == 4321
def test_windows_job_install_degrades_on_create_failure(monkeypatch):
log: list[str] = []
_patch_windows(monkeypatch, _FakeKernel32(log, create_ret = 0))
pl._install_windows_job()
assert pl._win_job_handle is None
assert "set" not in log
def test_windows_job_install_degrades_on_assign_failure(monkeypatch):
log: list[str] = []
_patch_windows(monkeypatch, _FakeKernel32(log, assign_ret = 0))
pl._install_windows_job()
assert pl._win_job_handle is None
assert "close" in log
_NESTED_CHILD_SCRIPT = """
import multiprocessing as mp
import sys
sys.path.insert(0, {backend!r})
CTX = mp.get_context("spawn")
def _grandchild(marker):
with open(marker, "w") as handle:
handle.write("ran")
def _worker(queue, marker):
try:
proc = CTX.Process(target = _grandchild, args = (marker,), daemon = True)
proc.start()
proc.join(30)
queue.put("started exit={{}}".format(proc.exitcode))
except Exception as exc:
queue.put("refused {{}}: {{}}".format(type(exc).__name__, exc))
def _no_shim(target, *args, **kwargs):
return target(*args, **kwargs)
if __name__ == "__main__":
from utils.native_path_leases import run_without_native_path_secret
arm, marker = sys.argv[1], sys.argv[2]
entry = run_without_native_path_secret if arm == "shim" else _no_shim
queue = CTX.Queue()
worker = CTX.Process(target = entry, args = (_worker, queue, marker), daemon = True)
worker.start()
print("parent-sees-daemon", worker.daemon, flush = True)
print("worker", queue.get(timeout = 60), flush = True)
worker.join(30)
"""
def _run_nested_child_arm(tmp_path, arm: str) -> tuple[str, bool]:
script = tmp_path / f"nested_{arm}.py"
script.write_text(_NESTED_CHILD_SCRIPT.format(backend = str(_BACKEND)))
marker = tmp_path / f"grandchild_{arm}.txt"
proc = subprocess.run(
[sys.executable, str(script), arm, str(marker)],
capture_output = True,
text = True,
timeout = 180,
)
assert proc.returncode == 0, proc.stderr
return proc.stdout, marker.exists()
@pytest.mark.skipif(
not __debug__,
reason = "CPython's daemonic-children guard is an assert, so -O strips it and a "
"daemonic worker spawns freely -- this arm would assert the opposite of "
"what it means",
)
def test_daemonic_worker_cannot_spawn_children_without_the_shim(tmp_path):
stdout, grandchild_ran = _run_nested_child_arm(tmp_path, "plain")
assert "refused AssertionError: daemonic processes are not allowed to have children" in stdout
assert not grandchild_ran
def test_daemonic_worker_spawns_children_through_the_shim(tmp_path):
stdout, grandchild_ran = _run_nested_child_arm(tmp_path, "shim")
assert "worker started exit=0" in stdout
assert grandchild_ran
assert "parent-sees-daemon True" in stdout
def test_allow_child_processes_clears_only_the_daemon_bit(monkeypatch):
# Do not mutate the pytest process's real multiprocessing config.
config = {"daemon": True, "authkey": b"secret", "semprefix": "/mp"}
monkeypatch.setattr(
multiprocessing.process, "current_process", lambda: type("P", (), {"_config": config})()
)
pl.allow_child_processes()
assert config == {"daemon": False, "authkey": b"secret", "semprefix": "/mp"}
def test_allow_child_processes_survives_a_missing_config(monkeypatch):
monkeypatch.setattr(multiprocessing.process, "current_process", lambda: type("P", (), {})())
pl.allow_child_processes()
def test_an_older_process_lifetime_still_gets_the_parent_death_binding(monkeypatch):
"""Import the names separately so a missing newer name cannot cost the parent-death binding."""
from utils import native_path_leases
calls = []
monkeypatch.setattr(pl, "bind_current_process_to_parent_lifetime", lambda: calls.append("bind"))
monkeypatch.delattr(pl, "allow_child_processes")
native_path_leases.run_without_native_path_secret(lambda: None)
assert calls == ["bind"]