EventDispatcher & @on_event
API reference for EventDispatcher, the @on_event listener decorator, and dynamic IoC-backed subscriber registration.
The EventDispatcher coordinates event subscriptions and concurrent asynchronous execution. It allows decoupled application services to communicate via event channels without holding direct references to each other.
Class Definition & Decorator
from zcore import EventDispatcher, on_event
# or: from zcore.kernel.events import EventDispatcher, on_eventDecorator: @on_event
Marks an asynchronous service method as an active subscriber for a specific event channel.
def on_event(event_name: str) -> Callable[[Any], Any]: ...Prop
Type
Class: EventDispatcher
class EventDispatcher:
def __init__(self) -> None:
...Methods
register_listeners
Inspects a service class for methods decorated with @on_event and registers them as lazy event handlers in the dispatcher.
def register_listeners(self, cls: Type[Any], container: Any) -> None: ...Prop
Type
Scoped Resolution: register_listeners does not instantiate the class immediately. When the event fires, it invokes container.resolve(cls) dynamically. This ensures that request-scoped dependencies (such as database sessions) are resolved cleanly within the active execution scope.
dispatch
Asynchronously dispatches an event, executing all registered handlers concurrently.
async def dispatch(
self,
event_name: str,
*args: Any,
**kwargs: Any
) -> list[Any]: ...Prop
Type
Concurrent Execution & Error Isolation:
- Asynchronous coroutines are gathered using
asyncio.gather(*tasks, return_exceptions=True). - Synchronous subscriber functions are executed inline safely.
- If an individual handler raises an unhandled exception,
EventDispatcherlogs the error with full traceback diagnostics, preventing a single failing subscriber from crashing other handlers or breaking the caller.
subscribe
Directly registers a standalone callback function to listen for an event channel.
def subscribe(self, event_name: str, handler: EventHandler) -> None: ...Prop
Type
unsubscribe
Deregisters a previously registered callback handler from an event channel.
def unsubscribe(self, event_name: str, handler: EventHandler) -> None: ...Prop
Type