"""DataLoader measurement and (opt-in) recommendation application. Spec 9.1 rules encoded: - MEASURE, always report. Windows notes included (spawn overhead, persistent worker memory, prefetch limits). - MUTATE only when training.dataloader_apply_recommendations=true. Even then we only fill values the user left at torch defaults; explicit user choices are detected via a signature comparison and preserved. Since Python cannot distinguish "num_workers=0 by default" from "user wrote 0", the applied recommendation set is written to the session report AND the change log so it is fully auditable and reversible. - All modifications happen through a guarded, restorable DataLoader.__init__ wrapper (see integration/hooks.py), never by editing user code. """ from __future__ import annotations from dataclasses import dataclass from typing import Optional from ..compat import require_torch @dataclass class DataLoaderStats: num_workers: int pin_memory: bool persistent_workers: bool prefetch_factor: Optional[int] batch_size: Optional[int] dataset_len: Optional[int] def summary(self) -> dict: return { "num_workers": self.num_workers, "pin_memory": self.pin_memory, "persistent_workers": self.persistent_workers, "prefetch_factor": self.prefetch_factor, "batch_size": self.batch_size, "dataset_len": self.dataset_len, } def measure(dataloader) -> DataLoaderStats: return DataLoaderStats( num_workers=getattr(dataloader, "num_workers", 0) or 0, pin_memory=bool(getattr(dataloader, "pin_memory", False)), persistent_workers=bool(getattr(dataloader, "persistent_workers", False)), prefetch_factor=getattr(dataloader, "prefetch_factor", None), batch_size=getattr(dataloader, "batch_size", None), dataset_len=len(dataloader.dataset) if hasattr(getattr(dataloader, "dataset", None), "__len__") else None, ) def _windows_is_spawning_constraint() -> bool: import sys return sys.platform.startswith("win") def recommend(stats: DataLoaderStats, has_cuda: bool, max_workers: int = 8) -> dict: """Windows-aware recommendations. These are ADVICE until applied.""" recs: dict = {} if _windows_is_spawning_constraint(): # Windows uses spawn: each worker re-imports the dataset module. # persistent_workers avoids paying that cost every epoch. recs["num_workers"] = min(max_workers, max(2, (stats.batch_size or 4) // 2)) recs["persistent_workers"] = True recs["prefetch_factor"] = 2 # keep modest; Windows worker RAM is real RAM recs["_windows_note"] = ( "spawn-based workers re-import your dataset module; if dataset objects " "are expensive to build, persistent_workers matters more than count" ) else: recs["num_workers"] = min(max_workers, max(4, (stats.batch_size or 8) // 2)) recs["persistent_workers"] = stats.num_workers > 0 recs["prefetch_factor"] = 2 recs["pin_memory"] = has_cuda recs["non_blocking_transfer"] = has_cuda # advisory for .to(device) calls return recs def diff(stats: DataLoaderStats, recs: dict) -> dict: """Which recommendations differ from current settings (report-friendly).""" out = {} for key in ("num_workers", "pin_memory", "persistent_workers", "prefetch_factor"): cur = getattr(stats, key, None) if key in recs and recs[key] != cur: out[key] = {"current": cur, "recommended": recs[key]} return out def apply_to_kwargs(user_kwargs: dict, stats: DataLoaderStats, recs: dict, apply_enabled: bool) -> tuple: """Guarded mutation for the hooks DataLoader wrapper. Only touches a key when (a) apply is enabled, (b) the user did not pass it explicitly, (c) the value differs from current. Returns (new_kwargs, changelog) where changelog documents every mutation. """ changelog = [] kwargs = dict(user_kwargs) if not apply_enabled: return kwargs, changelog # The wrapper sees the raw kwargs; a key present in kwargs was explicitly # set by the user -> never override (auditable rule). for key in ("num_workers", "pin_memory", "persistent_workers", "prefetch_factor"): if key in kwargs: continue if key in recs: cur = getattr(stats, key, None) if recs[key] != cur: kwargs[key] = recs[key] changelog.append({ "arg": key, "was_default": cur, "applied": recs[key], "why": "unset in user code; LPU filled recommended value", }) if kwargs.get("num_workers", 0) > 0 and "persistent_workers" not in user_kwargs: kwargs.setdefault("persistent_workers", True) return kwargs, changelog