Files
ComfyUI-H3-Continuum-Tiled/v3/file_backed_buffer.py
T
2026-08-24 14:24:25 +09:00

258 lines
8.5 KiB
Python

"""V3.5 adapter for the accepted P2-0 file-backed Tensor backend.
The storage and lifetime implementation remains in the P2-0 module so the
Windows-tested locking, sidecar, cancellation, and alias-lifetime contracts
have one implementation. This module only exposes the small Production API
needed by the V3.5 assembler.
"""
from __future__ import annotations
from dataclasses import dataclass
import os
from pathlib import Path
import shutil
import tempfile
import threading
import torch
from ..tools.p20_file_backed_tensor_poc import (
FileBackedAllocation,
StorageLifetimeManager,
cleanup_stale_files,
get_process_lifetime_manager,
)
BUFFER_BACKEND_AUTO = "Auto"
BUFFER_BACKEND_RAM = "RAM"
BUFFER_BACKEND_DISK = "Disk-backed"
BUFFER_BACKEND_OPTIONS = (
BUFFER_BACKEND_AUTO,
BUFFER_BACKEND_RAM,
BUFFER_BACKEND_DISK,
)
AUTO_RAM_IMAGE_LIMIT_BYTES = 4 * 1024**3
AUTO_RAM_RESERVE_MIN_BYTES = 4 * 1024**3
AUTO_RAM_RESERVE_FRACTION = 0.10
AUTO_DISK_RESERVE_BYTES = 2 * 1024**3
_BACKING_DIRECTORY_NAME = "h3-continuum-v35-file-backed"
_CLEANED_ROOTS: set[str] = set()
_CLEANED_ROOTS_LOCK = threading.Lock()
def validate_buffer_backend(value: str) -> str:
"""Validate the explicit or automatic V3.5 IMAGE backend request."""
if value not in BUFFER_BACKEND_OPTIONS:
raise ValueError(f"unknown Buffer Backend: {value!r}")
return value
@dataclass(frozen=True)
class AutoBufferDecision:
selected_backend: str
final_image_bytes: int
backing_root: Path
available_memory_bytes: int | None
total_memory_bytes: int | None
memory_reserve_bytes: int | None
ram_image_limit_bytes: int
disk_free_bytes: int | None
disk_reserve_bytes: int
reason: str
def _system_memory_bytes() -> tuple[int | None, int | None]:
try:
import psutil
counters = psutil.virtual_memory()
return int(counters.available), int(counters.total)
except Exception:
return None, None
def _existing_disk_anchor(path: Path) -> Path:
candidate = path
while not candidate.exists() and candidate != candidate.parent:
candidate = candidate.parent
if not candidate.exists():
raise OSError(f"no existing filesystem anchor for backing root: {path}")
return candidate
def _disk_free_bytes(path: Path) -> int:
return int(shutil.disk_usage(_existing_disk_anchor(path)).free)
def select_auto_buffer_backend(
final_image_bytes: int,
*,
backing_root: str | os.PathLike[str] | None = None,
) -> AutoBufferDecision:
"""Choose RAM only when both output size and physical headroom are safe.
Auto never converts a Disk-backed decision into RAM after a disk-space or
allocation failure. Users can still explicitly select either manual path.
"""
final_bytes = int(final_image_bytes)
if final_bytes <= 0:
raise ValueError("Auto Buffer Backend requires a positive final IMAGE size")
root = resolve_backing_root(backing_root)
available, total = _system_memory_bytes()
reserve = None
if available is not None and total is not None and total > 0:
reserve = max(
AUTO_RAM_RESERVE_MIN_BYTES,
int(total * AUTO_RAM_RESERVE_FRACTION),
)
if (
reserve is not None
and final_bytes <= AUTO_RAM_IMAGE_LIMIT_BYTES
and available >= final_bytes + reserve
):
return AutoBufferDecision(
selected_backend=BUFFER_BACKEND_RAM,
final_image_bytes=final_bytes,
backing_root=root,
available_memory_bytes=available,
total_memory_bytes=total,
memory_reserve_bytes=reserve,
ram_image_limit_bytes=AUTO_RAM_IMAGE_LIMIT_BYTES,
disk_free_bytes=None,
disk_reserve_bytes=AUTO_DISK_RESERVE_BYTES,
reason="final IMAGE fits the Auto RAM size limit and safety reserve",
)
if reserve is None:
reason = "physical-memory counters are unavailable"
elif final_bytes > AUTO_RAM_IMAGE_LIMIT_BYTES:
reason = "final IMAGE exceeds the Auto RAM size limit"
else:
reason = "available physical memory is below final IMAGE plus reserve"
try:
disk_free = _disk_free_bytes(root)
except Exception as exc:
raise RuntimeError(
"Auto Buffer Backend selected Disk-backed but disk capacity could "
f"not be measured for {root}: {type(exc).__name__}: {exc}. "
"Select RAM manually only if sufficient memory is known to be available."
) from exc
required_disk = final_bytes + AUTO_DISK_RESERVE_BYTES
if disk_free < required_disk:
raise RuntimeError(
"Auto Buffer Backend selected Disk-backed but the backing volume "
f"has {disk_free} free bytes; {required_disk} bytes are required "
f"for the final IMAGE plus the {AUTO_DISK_RESERVE_BYTES}-byte safety "
"reserve. Free disk space or select RAM manually only if sufficient "
"memory is known to be available."
)
return AutoBufferDecision(
selected_backend=BUFFER_BACKEND_DISK,
final_image_bytes=final_bytes,
backing_root=root,
available_memory_bytes=available,
total_memory_bytes=total,
memory_reserve_bytes=reserve,
ram_image_limit_bytes=AUTO_RAM_IMAGE_LIMIT_BYTES,
disk_free_bytes=disk_free,
disk_reserve_bytes=AUTO_DISK_RESERVE_BYTES,
reason=reason,
)
def format_auto_buffer_decision(decision: AutoBufferDecision) -> str:
def value(number: int | None) -> str:
return "n/a" if number is None else str(int(number))
return (
"Auto Buffer Decision: "
f"selected={decision.selected_backend}, "
f"final_IMAGE={decision.final_image_bytes} bytes, "
f"system_available={value(decision.available_memory_bytes)} bytes, "
f"system_total={value(decision.total_memory_bytes)} bytes, "
f"RAM_reserve={value(decision.memory_reserve_bytes)} bytes, "
f"RAM_IMAGE_limit={decision.ram_image_limit_bytes} bytes, "
f"disk_free={value(decision.disk_free_bytes)} bytes, "
f"disk_reserve={decision.disk_reserve_bytes} bytes; "
f"reason={decision.reason}."
)
def resolve_backing_root(
backing_root: str | os.PathLike[str] | None = None,
) -> Path:
"""Resolve the dedicated backing root without importing ComfyUI eagerly."""
if backing_root is not None:
return Path(backing_root).expanduser().resolve()
try:
import folder_paths
except ImportError:
base = Path(tempfile.gettempdir())
else:
value = folder_paths.get_temp_directory()
if value is None or not str(value).strip():
raise RuntimeError("ComfyUI returned an empty temporary directory")
base = Path(value)
return (base.expanduser().resolve() / _BACKING_DIRECTORY_NAME).resolve()
def get_file_backed_image_manager(
backing_root: str | os.PathLike[str] | None = None,
) -> StorageLifetimeManager:
"""Return the accepted process-global manager for one resolved root."""
root = resolve_backing_root(backing_root)
key = os.path.normcase(str(root))
with _CLEANED_ROOTS_LOCK:
if key not in _CLEANED_ROOTS:
# The P2-0 root lock prevents cleanup from observing an allocation
# between its data-file and sidecar publication. A live owner is
# always retained; only prior abnormal-exit artifacts are removed.
cleanup_stale_files(root, grace_seconds=0.0)
_CLEANED_ROOTS.add(key)
return get_process_lifetime_manager(root)
def allocate_file_backed_image(
shape: tuple[int, ...],
*,
dtype: torch.dtype,
backing_root: str | os.PathLike[str] | None = None,
) -> FileBackedAllocation:
"""Create a provisional Disk-backed IMAGE allocation.
The caller must use the returned context manager and call ``publish()``
only after every output element has been written. Backend failures are
propagated; this manual Disk-backed path never falls back to RAM.
"""
manager = get_file_backed_image_manager(backing_root)
return manager.allocate(shape, dtype=dtype)
__all__ = [
"AUTO_DISK_RESERVE_BYTES",
"AUTO_RAM_IMAGE_LIMIT_BYTES",
"AUTO_RAM_RESERVE_FRACTION",
"AUTO_RAM_RESERVE_MIN_BYTES",
"AutoBufferDecision",
"BUFFER_BACKEND_AUTO",
"BUFFER_BACKEND_DISK",
"BUFFER_BACKEND_OPTIONS",
"BUFFER_BACKEND_RAM",
"allocate_file_backed_image",
"format_auto_buffer_decision",
"get_file_backed_image_manager",
"resolve_backing_root",
"select_auto_buffer_backend",
"validate_buffer_backend",
]