"""Bounded daemon workers with a finite shutdown wait. Python cannot safely terminate a blocked thread. Owners cancel their browser resources on timeout and retain a failed group until those calls unwind. """ import logging import queue import threading from typing import Optional from utils.resource_lifecycle import join_threads class TaskExecutor: def __init__(self, max_workers: int, name: str): self._slots = threading.BoundedSemaphore(max_workers) self._queue = queue.Queue(maxsize=max_workers) self._lock = threading.Lock() self._closed = threading.Event() self._threads = [] self._max_workers = max_workers self._name = name def _worker(self): while not self._closed.is_set() or not self._queue.empty(): try: fn, args, kwargs = self._queue.get(timeout=0.05) except queue.Empty: continue try: fn(*args, **kwargs) except Exception: logging.getLogger(__name__).exception('Background job failed') finally: self._slots.release() self._queue.task_done() def submit(self, fn, *args, **kwargs): with self._lock: if self._closed.is_set() or not self._slots.acquire(blocking=False): return False try: if len(self._threads) < self._max_workers: thread = threading.Thread(target=self._worker, daemon=True, name=f'{self._name}-{len(self._threads)}') thread.start() self._threads.append(thread) self._queue.put_nowait((fn, args, kwargs)) except Exception: self._slots.release() raise return True def shutdown(self, timeout=5): with self._lock: self._closed.set() return join_threads(self._threads, timeout) _background_executor: Optional[TaskExecutor] = None _bg_lock = threading.Lock() def get_background_executor(max_workers: int = 16) -> TaskExecutor: """Returns a shared daemon background TaskExecutor for lightweight async jobs.""" global _background_executor if _background_executor is None: with _bg_lock: if _background_executor is None: _background_executor = TaskExecutor(max_workers=max_workers, name='Background') return _background_executor def submit_background(fn, *args, **kwargs) -> bool: """Convenience helper to submit a job to the shared background executor.""" return get_background_executor().submit(fn, *args, **kwargs)