| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573 |
- # -*- coding: utf-8 -*-
- """
- Event-Debouncing für verzögerte Ausführung.
- Führt nur das letzte Event einer Serie aus.
- """
- from __future__ import annotations
- import asyncio
- from dataclasses import dataclass, field
- from datetime import datetime
- from typing import TYPE_CHECKING, Any, Callable, Coroutine
- if TYPE_CHECKING:
- from trixy_core.events.event_data.base import EventData
- @dataclass
- class DebounceConfig:
- """
- Konfiguration für Event-Debouncing.
- """
- delay_ms: float = 300.0
- """Verzögerung in Millisekunden."""
- max_wait_ms: float | None = None
- """Maximale Wartezeit (None = unbegrenzt)."""
- leading: bool = False
- """Ob das erste Event sofort ausgeführt wird."""
- trailing: bool = True
- """Ob das letzte Event ausgeführt wird."""
- @dataclass
- class DebouncedEvent:
- """
- Ein debounce-verwaltetes Event.
- """
- event_name: str
- """Name des Events."""
- event_data: "EventData"
- """Die Event-Daten."""
- received_at: datetime = field(default_factory=datetime.now)
- """Zeitpunkt des Empfangs."""
- scheduled_at: datetime | None = None
- """Geplanter Ausführungszeitpunkt."""
- executed: bool = False
- """Ob das Event ausgeführt wurde."""
- @dataclass
- class DebounceState:
- """
- Zustand für einen Event-Typ.
- """
- pending_event: DebouncedEvent | None = None
- """Aktuell wartendes Event."""
- timer_task: asyncio.Task | None = None
- """Timer-Task."""
- first_event_at: datetime | None = None
- """Zeitpunkt des ersten Events der Serie."""
- executed_leading: bool = False
- """Ob Leading-Event ausgeführt wurde."""
- total_received: int = 0
- """Gesamtzahl empfangener Events."""
- total_executed: int = 0
- """Gesamtzahl ausgeführter Events."""
- total_dropped: int = 0
- """Gesamtzahl verworfener Events."""
- class EventDebouncer:
- """
- Debouncer für Events.
- Führt nur das letzte Event einer Serie aus, nachdem
- eine bestimmte Zeit ohne neue Events vergangen ist.
- Example:
- debouncer = EventDebouncer()
- # Konfiguration
- debouncer.set_debounce("search_input", delay_ms=300)
- debouncer.set_debounce("resize", delay_ms=100, max_wait_ms=1000)
- # Event verarbeiten
- async def on_search(event_data):
- print(f"Search: {event_data}")
- await debouncer.debounce("search_input", event_data, on_search)
- """
- def __init__(
- self,
- default_config: DebounceConfig | None = None,
- ) -> None:
- """
- Initialisiert den Debouncer.
- Args:
- default_config: Standard-Konfiguration.
- """
- self._default_config = default_config or DebounceConfig()
- self._configs: dict[str, DebounceConfig] = {}
- self._states: dict[str, DebounceState] = {}
- self._handlers: dict[str, Callable[["EventData"], Coroutine[Any, Any, None]]] = {}
- self._lock = asyncio.Lock()
- def set_debounce(
- self,
- event_name: str,
- delay_ms: float | None = None,
- max_wait_ms: float | None = None,
- leading: bool | None = None,
- trailing: bool | None = None,
- ) -> None:
- """
- Konfiguriert Debouncing für ein Event.
- Args:
- event_name: Name des Events.
- delay_ms: Verzögerung.
- max_wait_ms: Maximale Wartezeit.
- leading: Erstes Event sofort ausführen.
- trailing: Letztes Event ausführen.
- """
- config = DebounceConfig(
- delay_ms=delay_ms if delay_ms is not None else self._default_config.delay_ms,
- max_wait_ms=max_wait_ms if max_wait_ms is not None else self._default_config.max_wait_ms,
- leading=leading if leading is not None else self._default_config.leading,
- trailing=trailing if trailing is not None else self._default_config.trailing,
- )
- self._configs[event_name] = config
- def set_handler(
- self,
- event_name: str,
- handler: Callable[["EventData"], Coroutine[Any, Any, None]],
- ) -> None:
- """
- Setzt den Handler für ein Event.
- Args:
- event_name: Name des Events.
- handler: Handler-Funktion.
- """
- self._handlers[event_name] = handler
- def get_config(self, event_name: str) -> DebounceConfig:
- """
- Gibt die Konfiguration für ein Event zurück.
- Args:
- event_name: Name des Events.
- Returns:
- DebounceConfig.
- """
- return self._configs.get(event_name, self._default_config)
- def _get_state(self, event_name: str) -> DebounceState:
- """
- Gibt den Zustand für ein Event zurück.
- Args:
- event_name: Name des Events.
- Returns:
- DebounceState.
- """
- if event_name not in self._states:
- self._states[event_name] = DebounceState()
- return self._states[event_name]
- async def debounce(
- self,
- event_name: str,
- event_data: "EventData",
- handler: Callable[["EventData"], Coroutine[Any, Any, None]] | None = None,
- ) -> bool:
- """
- Debounced ein Event.
- Args:
- event_name: Name des Events.
- event_data: Die Event-Daten.
- handler: Optionaler Handler (überschreibt registrierten).
- Returns:
- True wenn Event sofort ausgeführt wurde (leading).
- """
- async with self._lock:
- config = self.get_config(event_name)
- state = self._get_state(event_name)
- handler = handler or self._handlers.get(event_name)
- if not handler:
- raise ValueError(f"Kein Handler für Event '{event_name}' registriert")
- state.total_received += 1
- now = datetime.now()
- # Erstes Event der Serie?
- is_first = state.pending_event is None and state.timer_task is None
- if is_first:
- state.first_event_at = now
- state.executed_leading = False
- # Pending Event aktualisieren
- debounced = DebouncedEvent(
- event_name=event_name,
- event_data=event_data,
- received_at=now,
- )
- # Altes Event verwerfen
- if state.pending_event:
- state.total_dropped += 1
- state.pending_event = debounced
- # Leading-Edge: Erstes Event sofort ausführen
- if is_first and config.leading and not state.executed_leading:
- state.executed_leading = True
- state.pending_event.executed = True
- state.total_executed += 1
- await handler(event_data)
- # Timer für trailing starten
- if config.trailing:
- self._schedule_trailing(event_name, config, state, handler)
- return True
- # Timer abbrechen falls vorhanden
- if state.timer_task and not state.timer_task.done():
- state.timer_task.cancel()
- # Max-Wait prüfen
- if config.max_wait_ms and state.first_event_at:
- elapsed = (now - state.first_event_at).total_seconds() * 1000
- if elapsed >= config.max_wait_ms:
- # Sofort ausführen
- state.pending_event.executed = True
- state.total_executed += 1
- state.first_event_at = now # Reset für nächste Serie
- await handler(event_data)
- return True
- # Timer für trailing starten
- if config.trailing:
- self._schedule_trailing(event_name, config, state, handler)
- return False
- def _schedule_trailing(
- self,
- event_name: str,
- config: DebounceConfig,
- state: DebounceState,
- handler: Callable[["EventData"], Coroutine[Any, Any, None]],
- ) -> None:
- """
- Plant die Trailing-Ausführung.
- Args:
- event_name: Name des Events.
- config: Konfiguration.
- state: Zustand.
- handler: Handler-Funktion.
- """
- async def execute_trailing():
- await asyncio.sleep(config.delay_ms / 1000)
- async with self._lock:
- if state.pending_event and not state.pending_event.executed:
- state.pending_event.executed = True
- state.total_executed += 1
- event_data = state.pending_event.event_data
- # Reset
- state.pending_event = None
- state.timer_task = None
- state.first_event_at = None
- state.executed_leading = False
- # Handler außerhalb des Locks ausführen
- await handler(event_data)
- state.timer_task = asyncio.create_task(execute_trailing())
- async def flush(self, event_name: str) -> bool:
- """
- Führt pending Event sofort aus.
- Args:
- event_name: Name des Events.
- Returns:
- True wenn Event ausgeführt wurde.
- """
- async with self._lock:
- state = self._states.get(event_name)
- if not state or not state.pending_event:
- return False
- # Timer abbrechen
- if state.timer_task and not state.timer_task.done():
- state.timer_task.cancel()
- # Event ausführen
- handler = self._handlers.get(event_name)
- if handler and not state.pending_event.executed:
- state.pending_event.executed = True
- state.total_executed += 1
- event_data = state.pending_event.event_data
- # Reset
- state.pending_event = None
- state.timer_task = None
- state.first_event_at = None
- state.executed_leading = False
- await handler(event_data)
- return True
- return False
- def cancel(self, event_name: str) -> bool:
- """
- Bricht pending Event ab.
- Args:
- event_name: Name des Events.
- Returns:
- True wenn Event abgebrochen wurde.
- """
- state = self._states.get(event_name)
- if not state:
- return False
- cancelled = False
- # Timer abbrechen
- if state.timer_task and not state.timer_task.done():
- state.timer_task.cancel()
- cancelled = True
- # Pending Event verwerfen
- if state.pending_event:
- state.total_dropped += 1
- cancelled = True
- # Reset
- state.pending_event = None
- state.timer_task = None
- state.first_event_at = None
- state.executed_leading = False
- return cancelled
- def is_pending(self, event_name: str) -> bool:
- """
- Prüft, ob ein Event pending ist.
- Args:
- event_name: Name des Events.
- Returns:
- True wenn Event wartet.
- """
- state = self._states.get(event_name)
- return state is not None and state.pending_event is not None
- def get_stats(self, event_name: str) -> dict[str, Any]:
- """
- Gibt Statistiken für ein Event zurück.
- Args:
- event_name: Name des Events.
- Returns:
- Statistik-Dictionary.
- """
- state = self._states.get(event_name)
- if not state:
- return {}
- config = self.get_config(event_name)
- return {
- "event_name": event_name,
- "total_received": state.total_received,
- "total_executed": state.total_executed,
- "total_dropped": state.total_dropped,
- "reduction_rate": (
- 1 - (state.total_executed / state.total_received)
- if state.total_received > 0
- else 0.0
- ),
- "is_pending": state.pending_event is not None,
- "delay_ms": config.delay_ms,
- "max_wait_ms": config.max_wait_ms,
- "leading": config.leading,
- "trailing": config.trailing,
- }
- def get_all_stats(self) -> dict[str, dict[str, Any]]:
- """
- Gibt Statistiken für alle Events zurück.
- Returns:
- Dictionary von Event-Namen zu Statistiken.
- """
- return {
- name: self.get_stats(name)
- for name in self._states.keys()
- }
- async def flush_all(self) -> int:
- """
- Führt alle pending Events aus.
- Returns:
- Anzahl ausgeführter Events.
- """
- count = 0
- for event_name in list(self._states.keys()):
- if await self.flush(event_name):
- count += 1
- return count
- def cancel_all(self) -> int:
- """
- Bricht alle pending Events ab.
- Returns:
- Anzahl abgebrochener Events.
- """
- count = 0
- for event_name in list(self._states.keys()):
- if self.cancel(event_name):
- count += 1
- return count
- def reset(self, event_name: str | None = None) -> None:
- """
- Setzt den Zustand zurück.
- Args:
- event_name: Optionaler Event-Name (None = alle).
- """
- if event_name:
- self.cancel(event_name)
- if event_name in self._states:
- del self._states[event_name]
- else:
- self.cancel_all()
- self._states.clear()
- def debounce(
- delay_ms: float = 300.0,
- max_wait_ms: float | None = None,
- leading: bool = False,
- trailing: bool = True,
- ) -> Callable:
- """
- Decorator für Debouncing einer Funktion.
- Args:
- delay_ms: Verzögerung in Millisekunden.
- max_wait_ms: Maximale Wartezeit.
- leading: Erstes Event sofort ausführen.
- trailing: Letztes Event ausführen.
- Returns:
- Decorator-Funktion.
- Example:
- @debounce(delay_ms=300)
- async def on_search(query: str):
- print(f"Searching: {query}")
- """
- def decorator(func: Callable) -> Callable:
- state = {
- "timer": None,
- "last_args": None,
- "last_kwargs": None,
- "first_call": None,
- "executed_leading": False,
- }
- lock = asyncio.Lock()
- async def wrapper(*args, **kwargs):
- async with lock:
- now = datetime.now()
- # Erstes Event der Serie?
- is_first = state["timer"] is None
- if is_first:
- state["first_call"] = now
- state["executed_leading"] = False
- state["last_args"] = args
- state["last_kwargs"] = kwargs
- # Leading-Edge
- if is_first and leading and not state["executed_leading"]:
- state["executed_leading"] = True
- if asyncio.iscoroutinefunction(func):
- return await func(*args, **kwargs)
- else:
- return func(*args, **kwargs)
- # Timer abbrechen
- if state["timer"] is not None:
- state["timer"].cancel()
- # Max-Wait prüfen
- if max_wait_ms and state["first_call"]:
- elapsed = (now - state["first_call"]).total_seconds() * 1000
- if elapsed >= max_wait_ms:
- state["first_call"] = now
- if asyncio.iscoroutinefunction(func):
- return await func(*args, **kwargs)
- else:
- return func(*args, **kwargs)
- # Timer starten
- if trailing:
- async def execute():
- await asyncio.sleep(delay_ms / 1000)
- async with lock:
- if state["last_args"] is not None:
- a, k = state["last_args"], state["last_kwargs"]
- state["last_args"] = None
- state["last_kwargs"] = None
- state["timer"] = None
- state["first_call"] = None
- state["executed_leading"] = False
- if asyncio.iscoroutinefunction(func):
- await func(*a, **k)
- else:
- func(*a, **k)
- state["timer"] = asyncio.create_task(execute())
- return None
- return wrapper
- return decorator
|