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
"""Classifies main-thread tasks from trace evidence; there is no catch-all for unexplained work."""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any, Iterable
from . import CellFailure
from .traceparse import Task, Thread, Trace, join_posted_from, walk_within_task
INPUT = "input"
TIMER = "timer"
MESSAGE_CHANNEL = "message_channel"
NETWORK = "network"
RAF = "raf"
IDLE = "idle"
GC = "gc"
BROWSER_INTERNAL = "browser_internal"
# Mostly the devtools pipe delivering `Runtime.evaluate`: our own cost, kept visible.
AGENT_IPC = "agent_ipc"
UNCLASSIFIED = "unclassified"
ORIGINS = (
INPUT,
TIMER,
MESSAGE_CHANNEL,
NETWORK,
RAF,
IDLE,
GC,
BROWSER_INTERNAL,
AGENT_IPC,
UNCLASSIFIED,
)
# Reported, never subtracted: a correction you cannot see you cannot check.
HARNESS_ORIGINS = (AGENT_IPC,)
UNCLASSIFIED_FAIL_PCT = 2.0
_JS_EVENTS = frozenset(
{
"FunctionCall",
"v8.callFunction",
"EvaluateScript",
"v8.run",
"v8.compile",
"V8.Execute",
}
)
_RESOURCE_EVENTS = frozenset(
{
"ResourceSendRequest",
"ResourceReceiveResponse",
"ResourceReceivedData",
"ResourceFinish",
"ResourceMarkAsCached",
"XHRReadyStateChange",
"XHRLoad",
}
)
_RAF_EVENTS = frozenset(
{
"FireAnimationFrame",
"AnimationFrame::Render",
"AnimationFrame::StyleAndLayout",
"BeginMainThreadFrame",
}
)
_INPUT_EVENT_TYPES = frozenset(
{
"keydown",
"keyup",
"keypress",
"beforeinput",
"input",
"compositionstart",
"compositionupdate",
"compositionend",
"textInput",
"mousedown",
"mouseup",
"mousemove",
"click",
"dblclick",
"wheel",
"pointerdown",
"pointerup",
"pointermove",
"pointercancel",
"touchstart",
"touchend",
"touchmove",
"gesturescrollbegin",
"gesturescrollupdate",
}
)
_NETWORK_EVENT_TYPES = frozenset({"message", "readystatechange", "load", "error", "open"})
_POSTED_FROM_RULES: tuple[tuple[str, str, str], ...] = (
# (src_file substring, src_func substring or "", origin)
("core/scheduler/dom_timer.cc", "", TIMER),
("blink/renderer/core/timing", "", TIMER),
("widget/input/main_thread_event_queue.cc", "", INPUT),
("blink/renderer/core/input", "", INPUT),
("cc/trees/proxy_impl.cc", "ScheduledActionSendBeginMainFrame", RAF),
("cc/trees/proxy_main.cc", "", RAF),
("v8/src/heap/", "", GC),
("blink/renderer/platform/heap/", "", GC),
("v8/src/tasks/", "", GC),
)
# Only applied to tasks that ran no page script, so it cannot swallow a JS bottleneck.
_BROWSER_INTERNAL_FILES = (
"web_frame_widget_impl.cc",
"main_thread_scheduler_impl.cc",
"trace_session_observer.cc",
"ipc_mojo_bootstrap.cc",
"simple_watcher.cc",
"render_media_client.cc",
"sandboxed_process_thread_type_handler.cc",
"memory_usage_monitor.cc",
"gpu.cc",
"interface_endpoint_client.cc",
"paint_timing.cc",
"layout_shift_tracker.cc",
"cc/trees/",
"perfetto_task_runner.cc",
"compositor_frame_reporting_controller.cc",
"frame_scheduler_impl.cc",
"page_scheduler_impl.cc",
)
_IDLE_MARKERS = ("DoIdleWork", "RunIdleTask", "IdleTask", "ScheduleIdleTask")
# Blink `TaskType` names, matched by substring after `TASK_TYPE_`.
_TASK_TYPE_RULES: tuple[tuple[str, str], ...] = (
("JAVASCRIPT_TIMER", TIMER),
("POSTED_MESSAGE", MESSAGE_CHANNEL),
("UNSHIPPED_PORT_MESSAGE", MESSAGE_CHANNEL),
("POST_MESSAGE_FORWARDING", MESSAGE_CHANNEL),
("USER_INTERACTION", INPUT),
("INPUT_BLOCKING", INPUT),
("MAIN_THREAD_TASK_QUEUE_INPUT", INPUT),
("NETWORKING", NETWORK),
("WEB_SOCKET", NETWORK),
("MAIN_THREAD_TASK_QUEUE_COMPOSITOR", RAF),
("COMPOSITOR_THREAD_TASK_QUEUE", RAF),
("IDLE_TASK", IDLE),
("MAIN_THREAD_TASK_QUEUE_IDLE", IDLE),
("MAIN_THREAD_TASK_QUEUE_V8", GC),
("MICROTASK", MESSAGE_CHANNEL),
)
_QUEUE_NAME_RULES: tuple[tuple[str, str], ...] = (
("INPUT_TQ", INPUT),
("UI_USER_INPUT_TQ", INPUT),
("COMPOSITOR_TQ", RAF),
("FRAME_THROTTLEABLE_TQ", TIMER),
("FRAME_LOADING_TQ", NETWORK),
("FRAME_LOADING_CONTROL_TQ", NETWORK),
("IDLE_TQ", IDLE),
("V8_TQ", GC),
("V8_USER_VISIBLE_TQ", GC),
("V8_BEST_EFFORT_TQ", GC),
)
def scheduler_labels(task: Task) -> dict[str, str]:
"""Blink's own task types from the scheduler category; empty when that category was not captured."""
for t in walk_within_task(task):
if t.name != "ThreadControllerImpl::RunTask":
continue
a = t.args or {}
exec_args = a.get("renderer_main_thread_task_execution") or {}
sm_args = a.get("sequence_manager_task") or {}
out: dict[str, str] = {}
if isinstance(exec_args, dict) and exec_args.get("task_type"):
out["task_type"] = str(exec_args["task_type"])
if isinstance(sm_args, dict) and sm_args.get("queue_name"):
out["queue_name"] = str(sm_args["queue_name"])
if isinstance(sm_args, dict) and sm_args.get("priority"):
out["priority"] = str(sm_args["priority"])
if out:
return out
return {}
@dataclass
class ClassifiedTask:
task: Task
origin: str
evidence: str
src_file: str = ""
src_func: str = ""
ran_js: bool = False
task_type: str = ""
queue_name: str = ""
@property
def dur_us(self) -> int:
return self.task.dur
def as_row(self) -> dict[str, Any]:
return {
"ts": self.task.ts,
"dur_us": self.task.dur,
"origin": self.origin,
"evidence": self.evidence,
"src_file": self.src_file,
"src_func": self.src_func,
"ran_js": self.ran_js,
"task_type": self.task_type,
"queue_name": self.queue_name,
}
@dataclass
class Classification:
tasks: list[ClassifiedTask] = field(default_factory = list)
by_origin_us: dict[str, int] = field(default_factory = dict)
by_origin_count: dict[str, int] = field(default_factory = dict)
total_us: int = 0
@property
def unclassified_pct(self) -> float:
if self.total_us <= 0:
return 0.0
return 100.0 * self.by_origin_us.get(UNCLASSIFIED, 0) / self.total_us
def assert_named(self, threshold_pct: float = UNCLASSIFIED_FAIL_PCT) -> None:
pct = self.unclassified_pct
if pct > threshold_pct:
worst = sorted(
(c for c in self.tasks if c.origin == UNCLASSIFIED),
key = lambda c: -c.dur_us,
)[:5]
detail = "; ".join(
f"{c.dur_us / 1000:.1f}ms from {c.src_file or '?'}::{c.src_func or '?'}"
f" [task_type={c.task_type or 'absent'} queue={c.queue_name or 'absent'}]"
for c in worst
)
raise CellFailure(
"unclassified_task_pct",
f"{pct:.2f}% of main-thread task time has no known origin "
f"(limit {threshold_pct}%). Worst: {detail}",
)
def summary(self) -> dict[str, Any]:
return {
"total_task_ms": self.total_us / 1000.0,
"unclassified_task_pct": round(self.unclassified_pct, 4),
"by_origin_ms": {k: round(v / 1000.0, 3) for k, v in sorted(self.by_origin_us.items())},
"by_origin_count": dict(sorted(self.by_origin_count.items())),
}
def tasks_of(self, origin: str) -> list[ClassifiedTask]:
return [c for c in self.tasks if c.origin == origin]
def windows_of(self, origin: str) -> list[tuple[int, int]]:
"""(start, end) microsecond windows, for slicing a CPU profile."""
return [(c.task.ts, c.task.end) for c in self.tasks_of(origin)]
def _nested_names(task: Task) -> set[str]:
return {t.name for t in walk_within_task(task) if t is not task}
def _event_dispatch_types(task: Task) -> set[str]:
out: set[str] = set()
for t in walk_within_task(task):
if t.name == "EventDispatch":
data = (t.args or {}).get("data") or {}
typ = data.get("type")
if isinstance(typ, str):
out.add(typ)
return out
def classify_task(task: Task) -> ClassifiedTask:
posted = join_posted_from(task)
src_file = str(posted.get("src_file", "") or "")
src_func = str(posted.get("src_func", "") or "")
names = _nested_names(task)
types = _event_dispatch_types(task)
ran_js = bool(names & _JS_EVENTS)
labels = scheduler_labels(task)
task_type = labels.get("task_type", "")
queue_name = labels.get("queue_name", "")
def done(origin: str, evidence: str) -> ClassifiedTask:
return ClassifiedTask(
task = task,
origin = origin,
evidence = evidence,
src_file = src_file,
src_func = src_func,
ran_js = ran_js,
task_type = task_type,
queue_name = queue_name,
)
# 0. Blink's own task type outranks everything. A V8 queue without JS is GC/compile bookkeeping;
# a compositor task with nested input dispatch is input.
if task_type:
if types & _INPUT_EVENT_TYPES:
return done(
INPUT,
f"task_type:{task_type}+EventDispatch:{sorted(types & _INPUT_EVENT_TYPES)[0]}",
)
for needle, origin in _TASK_TYPE_RULES:
if needle in task_type:
if origin == GC and ran_js:
continue
return done(origin, f"task_type:{task_type}")
# 1. Input first: input latency is what a user feels.
if types & _INPUT_EVENT_TYPES:
return done(INPUT, f"EventDispatch:{sorted(types & _INPUT_EVENT_TYPES)[0]}")
if "main_thread_event_queue.cc" in src_file:
return done(INPUT, "posted_from:main_thread_event_queue")
# 2. GC before anything that can contain it, e.g. a timer task running incremental marking.
gc_names = {
n
for n in names
if n.startswith("V8.GC") or n in ("MajorGC", "MinorGC", "BlinkGC.AtomicPhase")
}
if any(marker in src_file for marker in ("v8/src/heap/", "platform/heap/")):
return done(GC, f"posted_from:{src_file.rsplit('/', 1)[-1]}")
if gc_names and not ran_js:
return done(GC, f"nested:{sorted(gc_names)[0]}")
# 3. Rendering lifecycle.
if names & _RAF_EVENTS or "ScheduledActionSendBeginMainFrame" in src_func:
return done(RAF, "frame_lifecycle")
# 4. Idle.
if any(m in src_func or m in task.name for m in _IDLE_MARKERS) or "RunIdleTask" in names:
return done(IDLE, "idle_queue")
# 5. Timers.
if "TimerFire" in names:
return done(TIMER, "nested:TimerFire")
if "dom_timer.cc" in src_file:
return done(TIMER, "posted_from:dom_timer")
# 6. Network / SSE, before message-channel: both arrive over mojo.
if names & _RESOURCE_EVENTS:
return done(NETWORK, f"nested:{sorted(names & _RESOURCE_EVENTS)[0]}")
if types & _NETWORK_EVENT_TYPES and "connector.cc" in src_file:
return done(NETWORK, f"EventDispatch:{sorted(types & _NETWORK_EVENT_TYPES)[0]}")
# 7. Message channel (React scheduler): page script ran and nothing network-shaped happened.
if ran_js and (
"connector.cc" in src_file
or "message_port" in src_file
or "interface_endpoint_client.cc" in src_file
):
return done(MESSAGE_CHANNEL, "mojo_pipe_running_page_script")
# 8. Devtools IPC running page script: measurement cost, never subtracted.
if ran_js and any(
f in src_file for f in ("ipc_mojo_bootstrap.cc", "simple_watcher.cc", "mojo_bootstrap")
):
return done(AGENT_IPC, f"posted_from:{src_file.rsplit('/', 1)[-1]}")
# 9. Browser bookkeeping, only when no page script ran.
if not ran_js and any(f in src_file for f in _BROWSER_INTERNAL_FILES):
return done(BROWSER_INTERNAL, f"posted_from:{src_file.rsplit('/', 1)[-1]}")
for needle, func_needle, origin in _POSTED_FROM_RULES:
if needle in src_file and (not func_needle or func_needle in src_func):
return done(origin, f"posted_from:{needle}")
# 10. Last resort: the queue the task sat on.
for needle, origin in _QUEUE_NAME_RULES:
if needle == queue_name:
if origin == GC and ran_js:
continue
return done(origin, f"queue_name:{queue_name}")
return done(
UNCLASSIFIED,
f"no rule for {src_file or 'unknown'}::{src_func or 'unknown'}"
+ (" (ran JS)" if ran_js else ""),
)
def classify_thread(trace: Trace, thread: Thread | None = None) -> Classification:
th = thread if thread is not None else trace.renderer_main()
result = Classification()
for task in trace.run_tasks(th):
c = classify_task(task)
result.tasks.append(c)
result.by_origin_us[c.origin] = result.by_origin_us.get(c.origin, 0) + c.dur_us
result.by_origin_count[c.origin] = result.by_origin_count.get(c.origin, 0) + 1
result.total_us += c.dur_us
return result
def cross_check_task_duration(
classification: Classification,
cdp_task_duration_s: float,
tolerance: float = 0.05,
) -> dict[str, Any]:
"""Trace RunTask sum must match Performance.getMetrics TaskDuration, else nothing derived is safe."""
trace_s = classification.total_us / 1e6
if cdp_task_duration_s <= 0:
raise CellFailure("task_duration_zero", "Performance.getMetrics reported TaskDuration <= 0")
drift = abs(trace_s - cdp_task_duration_s) / cdp_task_duration_s
report = {
"trace_run_task_s": trace_s,
"cdp_task_duration_s": cdp_task_duration_s,
"drift": drift,
"tolerance": tolerance,
}
if drift > tolerance:
raise CellFailure(
"task_duration_mismatch",
f"trace RunTask total {trace_s * 1000:.1f} ms vs CDP TaskDuration "
f"{cdp_task_duration_s * 1000:.1f} ms = {drift * 100:.1f}% apart, "
f"above {tolerance * 100:.0f}%",
)
return report
def origin_windows(classification: Classification, origins: Iterable[str]) -> list[tuple[int, int]]:
wanted = set(origins)
return [(c.task.ts, c.task.end) for c in classification.tasks if c.origin in wanted]