debounce.py 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573
  1. # -*- coding: utf-8 -*-
  2. """
  3. Event-Debouncing für verzögerte Ausführung.
  4. Führt nur das letzte Event einer Serie aus.
  5. """
  6. from __future__ import annotations
  7. import asyncio
  8. from dataclasses import dataclass, field
  9. from datetime import datetime
  10. from typing import TYPE_CHECKING, Any, Callable, Coroutine
  11. if TYPE_CHECKING:
  12. from trixy_core.events.event_data.base import EventData
  13. @dataclass
  14. class DebounceConfig:
  15. """
  16. Konfiguration für Event-Debouncing.
  17. """
  18. delay_ms: float = 300.0
  19. """Verzögerung in Millisekunden."""
  20. max_wait_ms: float | None = None
  21. """Maximale Wartezeit (None = unbegrenzt)."""
  22. leading: bool = False
  23. """Ob das erste Event sofort ausgeführt wird."""
  24. trailing: bool = True
  25. """Ob das letzte Event ausgeführt wird."""
  26. @dataclass
  27. class DebouncedEvent:
  28. """
  29. Ein debounce-verwaltetes Event.
  30. """
  31. event_name: str
  32. """Name des Events."""
  33. event_data: "EventData"
  34. """Die Event-Daten."""
  35. received_at: datetime = field(default_factory=datetime.now)
  36. """Zeitpunkt des Empfangs."""
  37. scheduled_at: datetime | None = None
  38. """Geplanter Ausführungszeitpunkt."""
  39. executed: bool = False
  40. """Ob das Event ausgeführt wurde."""
  41. @dataclass
  42. class DebounceState:
  43. """
  44. Zustand für einen Event-Typ.
  45. """
  46. pending_event: DebouncedEvent | None = None
  47. """Aktuell wartendes Event."""
  48. timer_task: asyncio.Task | None = None
  49. """Timer-Task."""
  50. first_event_at: datetime | None = None
  51. """Zeitpunkt des ersten Events der Serie."""
  52. executed_leading: bool = False
  53. """Ob Leading-Event ausgeführt wurde."""
  54. total_received: int = 0
  55. """Gesamtzahl empfangener Events."""
  56. total_executed: int = 0
  57. """Gesamtzahl ausgeführter Events."""
  58. total_dropped: int = 0
  59. """Gesamtzahl verworfener Events."""
  60. class EventDebouncer:
  61. """
  62. Debouncer für Events.
  63. Führt nur das letzte Event einer Serie aus, nachdem
  64. eine bestimmte Zeit ohne neue Events vergangen ist.
  65. Example:
  66. debouncer = EventDebouncer()
  67. # Konfiguration
  68. debouncer.set_debounce("search_input", delay_ms=300)
  69. debouncer.set_debounce("resize", delay_ms=100, max_wait_ms=1000)
  70. # Event verarbeiten
  71. async def on_search(event_data):
  72. print(f"Search: {event_data}")
  73. await debouncer.debounce("search_input", event_data, on_search)
  74. """
  75. def __init__(
  76. self,
  77. default_config: DebounceConfig | None = None,
  78. ) -> None:
  79. """
  80. Initialisiert den Debouncer.
  81. Args:
  82. default_config: Standard-Konfiguration.
  83. """
  84. self._default_config = default_config or DebounceConfig()
  85. self._configs: dict[str, DebounceConfig] = {}
  86. self._states: dict[str, DebounceState] = {}
  87. self._handlers: dict[str, Callable[["EventData"], Coroutine[Any, Any, None]]] = {}
  88. self._lock = asyncio.Lock()
  89. def set_debounce(
  90. self,
  91. event_name: str,
  92. delay_ms: float | None = None,
  93. max_wait_ms: float | None = None,
  94. leading: bool | None = None,
  95. trailing: bool | None = None,
  96. ) -> None:
  97. """
  98. Konfiguriert Debouncing für ein Event.
  99. Args:
  100. event_name: Name des Events.
  101. delay_ms: Verzögerung.
  102. max_wait_ms: Maximale Wartezeit.
  103. leading: Erstes Event sofort ausführen.
  104. trailing: Letztes Event ausführen.
  105. """
  106. config = DebounceConfig(
  107. delay_ms=delay_ms if delay_ms is not None else self._default_config.delay_ms,
  108. max_wait_ms=max_wait_ms if max_wait_ms is not None else self._default_config.max_wait_ms,
  109. leading=leading if leading is not None else self._default_config.leading,
  110. trailing=trailing if trailing is not None else self._default_config.trailing,
  111. )
  112. self._configs[event_name] = config
  113. def set_handler(
  114. self,
  115. event_name: str,
  116. handler: Callable[["EventData"], Coroutine[Any, Any, None]],
  117. ) -> None:
  118. """
  119. Setzt den Handler für ein Event.
  120. Args:
  121. event_name: Name des Events.
  122. handler: Handler-Funktion.
  123. """
  124. self._handlers[event_name] = handler
  125. def get_config(self, event_name: str) -> DebounceConfig:
  126. """
  127. Gibt die Konfiguration für ein Event zurück.
  128. Args:
  129. event_name: Name des Events.
  130. Returns:
  131. DebounceConfig.
  132. """
  133. return self._configs.get(event_name, self._default_config)
  134. def _get_state(self, event_name: str) -> DebounceState:
  135. """
  136. Gibt den Zustand für ein Event zurück.
  137. Args:
  138. event_name: Name des Events.
  139. Returns:
  140. DebounceState.
  141. """
  142. if event_name not in self._states:
  143. self._states[event_name] = DebounceState()
  144. return self._states[event_name]
  145. async def debounce(
  146. self,
  147. event_name: str,
  148. event_data: "EventData",
  149. handler: Callable[["EventData"], Coroutine[Any, Any, None]] | None = None,
  150. ) -> bool:
  151. """
  152. Debounced ein Event.
  153. Args:
  154. event_name: Name des Events.
  155. event_data: Die Event-Daten.
  156. handler: Optionaler Handler (überschreibt registrierten).
  157. Returns:
  158. True wenn Event sofort ausgeführt wurde (leading).
  159. """
  160. async with self._lock:
  161. config = self.get_config(event_name)
  162. state = self._get_state(event_name)
  163. handler = handler or self._handlers.get(event_name)
  164. if not handler:
  165. raise ValueError(f"Kein Handler für Event '{event_name}' registriert")
  166. state.total_received += 1
  167. now = datetime.now()
  168. # Erstes Event der Serie?
  169. is_first = state.pending_event is None and state.timer_task is None
  170. if is_first:
  171. state.first_event_at = now
  172. state.executed_leading = False
  173. # Pending Event aktualisieren
  174. debounced = DebouncedEvent(
  175. event_name=event_name,
  176. event_data=event_data,
  177. received_at=now,
  178. )
  179. # Altes Event verwerfen
  180. if state.pending_event:
  181. state.total_dropped += 1
  182. state.pending_event = debounced
  183. # Leading-Edge: Erstes Event sofort ausführen
  184. if is_first and config.leading and not state.executed_leading:
  185. state.executed_leading = True
  186. state.pending_event.executed = True
  187. state.total_executed += 1
  188. await handler(event_data)
  189. # Timer für trailing starten
  190. if config.trailing:
  191. self._schedule_trailing(event_name, config, state, handler)
  192. return True
  193. # Timer abbrechen falls vorhanden
  194. if state.timer_task and not state.timer_task.done():
  195. state.timer_task.cancel()
  196. # Max-Wait prüfen
  197. if config.max_wait_ms and state.first_event_at:
  198. elapsed = (now - state.first_event_at).total_seconds() * 1000
  199. if elapsed >= config.max_wait_ms:
  200. # Sofort ausführen
  201. state.pending_event.executed = True
  202. state.total_executed += 1
  203. state.first_event_at = now # Reset für nächste Serie
  204. await handler(event_data)
  205. return True
  206. # Timer für trailing starten
  207. if config.trailing:
  208. self._schedule_trailing(event_name, config, state, handler)
  209. return False
  210. def _schedule_trailing(
  211. self,
  212. event_name: str,
  213. config: DebounceConfig,
  214. state: DebounceState,
  215. handler: Callable[["EventData"], Coroutine[Any, Any, None]],
  216. ) -> None:
  217. """
  218. Plant die Trailing-Ausführung.
  219. Args:
  220. event_name: Name des Events.
  221. config: Konfiguration.
  222. state: Zustand.
  223. handler: Handler-Funktion.
  224. """
  225. async def execute_trailing():
  226. await asyncio.sleep(config.delay_ms / 1000)
  227. async with self._lock:
  228. if state.pending_event and not state.pending_event.executed:
  229. state.pending_event.executed = True
  230. state.total_executed += 1
  231. event_data = state.pending_event.event_data
  232. # Reset
  233. state.pending_event = None
  234. state.timer_task = None
  235. state.first_event_at = None
  236. state.executed_leading = False
  237. # Handler außerhalb des Locks ausführen
  238. await handler(event_data)
  239. state.timer_task = asyncio.create_task(execute_trailing())
  240. async def flush(self, event_name: str) -> bool:
  241. """
  242. Führt pending Event sofort aus.
  243. Args:
  244. event_name: Name des Events.
  245. Returns:
  246. True wenn Event ausgeführt wurde.
  247. """
  248. async with self._lock:
  249. state = self._states.get(event_name)
  250. if not state or not state.pending_event:
  251. return False
  252. # Timer abbrechen
  253. if state.timer_task and not state.timer_task.done():
  254. state.timer_task.cancel()
  255. # Event ausführen
  256. handler = self._handlers.get(event_name)
  257. if handler and not state.pending_event.executed:
  258. state.pending_event.executed = True
  259. state.total_executed += 1
  260. event_data = state.pending_event.event_data
  261. # Reset
  262. state.pending_event = None
  263. state.timer_task = None
  264. state.first_event_at = None
  265. state.executed_leading = False
  266. await handler(event_data)
  267. return True
  268. return False
  269. def cancel(self, event_name: str) -> bool:
  270. """
  271. Bricht pending Event ab.
  272. Args:
  273. event_name: Name des Events.
  274. Returns:
  275. True wenn Event abgebrochen wurde.
  276. """
  277. state = self._states.get(event_name)
  278. if not state:
  279. return False
  280. cancelled = False
  281. # Timer abbrechen
  282. if state.timer_task and not state.timer_task.done():
  283. state.timer_task.cancel()
  284. cancelled = True
  285. # Pending Event verwerfen
  286. if state.pending_event:
  287. state.total_dropped += 1
  288. cancelled = True
  289. # Reset
  290. state.pending_event = None
  291. state.timer_task = None
  292. state.first_event_at = None
  293. state.executed_leading = False
  294. return cancelled
  295. def is_pending(self, event_name: str) -> bool:
  296. """
  297. Prüft, ob ein Event pending ist.
  298. Args:
  299. event_name: Name des Events.
  300. Returns:
  301. True wenn Event wartet.
  302. """
  303. state = self._states.get(event_name)
  304. return state is not None and state.pending_event is not None
  305. def get_stats(self, event_name: str) -> dict[str, Any]:
  306. """
  307. Gibt Statistiken für ein Event zurück.
  308. Args:
  309. event_name: Name des Events.
  310. Returns:
  311. Statistik-Dictionary.
  312. """
  313. state = self._states.get(event_name)
  314. if not state:
  315. return {}
  316. config = self.get_config(event_name)
  317. return {
  318. "event_name": event_name,
  319. "total_received": state.total_received,
  320. "total_executed": state.total_executed,
  321. "total_dropped": state.total_dropped,
  322. "reduction_rate": (
  323. 1 - (state.total_executed / state.total_received)
  324. if state.total_received > 0
  325. else 0.0
  326. ),
  327. "is_pending": state.pending_event is not None,
  328. "delay_ms": config.delay_ms,
  329. "max_wait_ms": config.max_wait_ms,
  330. "leading": config.leading,
  331. "trailing": config.trailing,
  332. }
  333. def get_all_stats(self) -> dict[str, dict[str, Any]]:
  334. """
  335. Gibt Statistiken für alle Events zurück.
  336. Returns:
  337. Dictionary von Event-Namen zu Statistiken.
  338. """
  339. return {
  340. name: self.get_stats(name)
  341. for name in self._states.keys()
  342. }
  343. async def flush_all(self) -> int:
  344. """
  345. Führt alle pending Events aus.
  346. Returns:
  347. Anzahl ausgeführter Events.
  348. """
  349. count = 0
  350. for event_name in list(self._states.keys()):
  351. if await self.flush(event_name):
  352. count += 1
  353. return count
  354. def cancel_all(self) -> int:
  355. """
  356. Bricht alle pending Events ab.
  357. Returns:
  358. Anzahl abgebrochener Events.
  359. """
  360. count = 0
  361. for event_name in list(self._states.keys()):
  362. if self.cancel(event_name):
  363. count += 1
  364. return count
  365. def reset(self, event_name: str | None = None) -> None:
  366. """
  367. Setzt den Zustand zurück.
  368. Args:
  369. event_name: Optionaler Event-Name (None = alle).
  370. """
  371. if event_name:
  372. self.cancel(event_name)
  373. if event_name in self._states:
  374. del self._states[event_name]
  375. else:
  376. self.cancel_all()
  377. self._states.clear()
  378. def debounce(
  379. delay_ms: float = 300.0,
  380. max_wait_ms: float | None = None,
  381. leading: bool = False,
  382. trailing: bool = True,
  383. ) -> Callable:
  384. """
  385. Decorator für Debouncing einer Funktion.
  386. Args:
  387. delay_ms: Verzögerung in Millisekunden.
  388. max_wait_ms: Maximale Wartezeit.
  389. leading: Erstes Event sofort ausführen.
  390. trailing: Letztes Event ausführen.
  391. Returns:
  392. Decorator-Funktion.
  393. Example:
  394. @debounce(delay_ms=300)
  395. async def on_search(query: str):
  396. print(f"Searching: {query}")
  397. """
  398. def decorator(func: Callable) -> Callable:
  399. state = {
  400. "timer": None,
  401. "last_args": None,
  402. "last_kwargs": None,
  403. "first_call": None,
  404. "executed_leading": False,
  405. }
  406. lock = asyncio.Lock()
  407. async def wrapper(*args, **kwargs):
  408. async with lock:
  409. now = datetime.now()
  410. # Erstes Event der Serie?
  411. is_first = state["timer"] is None
  412. if is_first:
  413. state["first_call"] = now
  414. state["executed_leading"] = False
  415. state["last_args"] = args
  416. state["last_kwargs"] = kwargs
  417. # Leading-Edge
  418. if is_first and leading and not state["executed_leading"]:
  419. state["executed_leading"] = True
  420. if asyncio.iscoroutinefunction(func):
  421. return await func(*args, **kwargs)
  422. else:
  423. return func(*args, **kwargs)
  424. # Timer abbrechen
  425. if state["timer"] is not None:
  426. state["timer"].cancel()
  427. # Max-Wait prüfen
  428. if max_wait_ms and state["first_call"]:
  429. elapsed = (now - state["first_call"]).total_seconds() * 1000
  430. if elapsed >= max_wait_ms:
  431. state["first_call"] = now
  432. if asyncio.iscoroutinefunction(func):
  433. return await func(*args, **kwargs)
  434. else:
  435. return func(*args, **kwargs)
  436. # Timer starten
  437. if trailing:
  438. async def execute():
  439. await asyncio.sleep(delay_ms / 1000)
  440. async with lock:
  441. if state["last_args"] is not None:
  442. a, k = state["last_args"], state["last_kwargs"]
  443. state["last_args"] = None
  444. state["last_kwargs"] = None
  445. state["timer"] = None
  446. state["first_call"] = None
  447. state["executed_leading"] = False
  448. if asyncio.iscoroutinefunction(func):
  449. await func(*a, **k)
  450. else:
  451. func(*a, **k)
  452. state["timer"] = asyncio.create_task(execute())
  453. return None
  454. return wrapper
  455. return decorator