PyEventEngine 0.6.2__cp315-cp315t-win_amd64.whl

event_engine/capi/c_event.pyi

@@ -0,0 +1,265 @@
+from collections.abc import Callable, Iterator
+from logging import Logger
+from typing import TypedDict
+
+from .c_topic import Topic
+
+
+class MessagePayload:
+    """
+    Python wrapper for a C message payload structure.
+
+    Attributes:
+        owner (bool): Indicates whether this instance owns the underlying C payload.
+    """
+
+    owner: bool
+
+    def __init__(self, topic: Topic, args: tuple, kwargs: dict) -> None:
+        """
+        Initialize a ``MessagePayload`` instance.
+
+        Args:
+            topic (Topic): Topic for this payload
+            args (tuple): Positional arguments for this payload
+            kwargs (dict): Keyword arguments for this payload
+        """
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the payload.
+        """
+
+    @property
+    def topic(self) -> Topic:
+        """
+        The topic associated with this payload.
+        """
+
+    @property
+    def args(self) -> tuple | None:
+        """
+        The positional arguments of the payload.
+        """
+
+    @property
+    def kwargs(self) -> dict | None:
+        """
+        The keyword arguments of the payload.
+        """
+
+    @property
+    def seq_id(self) -> int:
+        """
+        The sequence ID of the payload.
+        """
+
+
+class EvtPyCallable(TypedDict):
+    fn: Callable[...]
+    logger: Logger
+    idx: int
+    with_topic: bool
+
+
+class EventHook:
+    """
+    Event dispatcher for registering and triggering handlers.
+
+    Handlers are triggered with a ``MessagePayload``. The dispatcher supports two calling conventions:
+    - **With-topic**: the handler receives the topic as a positional or keyword argument.
+    - **No-topic**: the handler receives only ``args`` and ``kwargs`` from the payload.
+
+    Handlers that accept ``**kwargs`` are recommended to ensure compatibility with both conventions.
+
+    Attributes:
+        topic (Topic): The topic associated with this hook.
+        logger (Logger | None): Optional logger instance. If not provided, use module global logger.
+    """
+
+    topic: Topic
+    logger: Logger
+
+    def __init__(self, topic: Topic, logger: Logger = None) -> None:
+        """
+        Initialize an ``EventHook``.
+
+        Args:
+            topic: The topic associated with this hook.
+            logger: Optional logger instance.
+        """
+
+    def __call__(self, msg: MessagePayload) -> None:
+        """
+        Trigger all registered handlers with the given message payload.
+
+        Alias for method ``trigger``.
+
+        Args:
+            msg: The message payload to dispatch to handlers.
+        """
+
+    def __iadd__(self, handler: Callable) -> EventHook:
+        """
+        Add a handler using the ``+=`` operator.
+
+        Args:
+            handler: The callable to register.
+        Returns:
+            Self, for chaining.
+        """
+
+    def __isub__(self, handler: Callable) -> EventHook:
+        """
+        Remove a handler using the ``-=`` operator.
+
+        Args:
+            handler: The callable to unregister.
+        Returns:
+            Self, for chaining.
+        """
+
+    def __len__(self) -> int:
+        """
+        Return the number of registered handlers.
+        """
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the ``EventHook``.
+        """
+
+    def __iter__(self) -> Iterator[Callable]:
+        """
+        Iterate over all registered handlers.
+        """
+
+    def __contains__(self, handler: Callable) -> bool:
+        """
+        Check if a handler is registered.
+
+        Args:
+            handler: The callable to check.
+        Returns:
+            ``True`` if the handler is registered; ``False`` otherwise.
+        """
+
+    def trigger(self, msg: MessagePayload) -> None:
+        """
+        Trigger all registered handlers with the given message payload.
+
+        Args:
+            msg: The message payload to dispatch.
+        """
+
+    def add_handler(self, handler: Callable, logger: Logger = None, deduplicate: bool = False) -> None:
+        """
+        Register a new handler.
+
+        It is strongly recommended that handlers accept ``**kwargs`` to remain compatible with both
+        with-topic and no-topic calling conventions.
+
+        Args:
+            handler: The callable to register.
+            logger: Optional logger instance for this handler. If not provided, use the hook's logger.
+            deduplicate: If ``True``, skip registration if the handler is already present.
+        """
+
+    def remove_handler(self, handler: Callable) -> EventHook:
+        """
+        Remove a handler from the hook.
+
+        Only the first matching occurrence is removed. If the same callable was added multiple times,
+        subsequent instances remain registered.
+
+        Args:
+            handler: The callable to remove.
+
+        Returns:
+            Self, for chaining.
+        """
+
+    def clear(self) -> None:
+        """
+        Remove all registered handlers.
+        """
+
+    @property
+    def handlers(self) -> list[EvtPyCallable]:
+        """
+        List all registered handlers.
+
+        Returns:
+            A list of dictionaries, each containing information about a registered handler.
+        """
+
+
+class HandlerStats(TypedDict):
+    n_calls: int
+    last_call_start: float
+    last_call_complete: float
+    elapsed_seconds: float
+
+
+class EventHookEx(EventHook):
+    """
+    Extended ``EventHook`` that tracks per-handler execution statistics.
+    """
+
+    def __init__(self, topic: object, logger: object = None) -> None:
+        """
+        Initialize an ``EventHookEx``.
+
+        Args:
+            topic: The topic associated with this hook.
+            logger: Optional logger instance.
+        """
+
+    @property
+    def stats(self) -> HandlerStats:
+        """
+        Get aggregate statistics for this EventHook
+
+        Returns:
+            A dictionary with total calls and total execution time.
+        """
+        ...
+
+
+class EventTestToolkit:
+    """Relays internal C event-hook state to Python for test validation.
+
+    Note:
+        Test-only class. Not declared in any ``.pxd``; not part of the
+        public package API.
+    """
+
+    @staticmethod
+    def get_n_callbacks(hook: EventHook) -> int:
+        """Number of C callbacks registered on the hook."""
+        ...
+
+    @staticmethod
+    def get_n_pre_watchers(hook: EventHook) -> int:
+        """Number of pre-invoked watchers registered on the hook."""
+        ...
+
+    @staticmethod
+    def get_n_post_watchers(hook: EventHook) -> int:
+        """Number of post-invoked watchers registered on the hook."""
+        ...
+
+    @staticmethod
+    def get_callable_count(hook: EventHook) -> int:
+        """Length of the Python-callable linked list."""
+        ...
+
+    @staticmethod
+    def get_callable_with_topic(hook: EventHook, idx: int) -> bool:
+        """Whether the callable at ``idx`` is invoked with the topic kwarg."""
+        ...
+
+    @staticmethod
+    def get_hook_topic_addr(hook: EventHook) -> int:
+        """Address of the C topic backing the hook."""
+        ...

event_engine/capi/c_event.pyx

@@ -0,0 +1,444 @@
+import inspect
+import traceback
+
+from cpython.exc cimport PyErr_Clear, PyErr_Fetch
+from cpython.method cimport PyMethod_Check, PyMethod_GET_FUNCTION, PyMethod_GET_SELF
+from cpython.ref cimport Py_XDECREF, Py_XINCREF
+from cpython.time cimport perf_counter
+from libc.stdint cimport uintptr_t
+
+from cbase.allocator_protocol.c_allocator_protocol cimport c_ap_alloc, c_ap_free, c_ap_protocol_from_ptr
+
+from ..base.c_allocator_protocol cimport EE_HEAP_ALLOCATOR
+from ..base import LOGGER
+
+LOGGER = LOGGER.getChild('Event')
+
+cdef tuple EMPTY_ARGS = ()
+cdef str TOPIC_FIELD_NAME = 'topic'
+
+
+cdef inline evt_message_payload* c_evt_payload_new(Topic topic, tuple args, dict kwargs):
+    cdef size_t payload_size = sizeof(evt_message_payload) + sizeof(evt_py_payload)
+    cdef evt_message_payload* c_payload = <evt_message_payload*> c_ap_alloc(payload_size, EE_HEAP_ALLOCATOR)
+    if not c_payload:
+        return NULL
+
+    cdef evt_py_payload* py_payload = <evt_py_payload*> (c_payload + 1)
+    cdef PyObject* kwargs_aggregated = PyDict_Copy(<PyObject*> kwargs)
+    PyDict_SetDefault(kwargs_aggregated, <PyObject*> TOPIC_FIELD_NAME, <PyObject*> topic)
+
+    py_payload.py_topic = <PyObject*> topic
+    py_payload.py_args = <PyObject*> args
+    py_payload.py_kwargs = <PyObject*> kwargs
+    py_payload.py_kwargs_aggregated = kwargs_aggregated
+
+    Py_XINCREF(<PyObject*> topic)
+    Py_XINCREF(<PyObject*> args)
+    Py_XINCREF(<PyObject*> kwargs)
+    # Py_XINCREF(<PyObject*> kwargs_aggregated)
+
+    c_payload.args = py_payload
+    c_payload.topic = topic.header
+    return c_payload
+
+
+cdef inline void c_evt_payload_free(evt_message_payload* payload):
+    cdef evt_py_payload* py_payload = <evt_py_payload*> (payload + 1)
+
+    Py_XDECREF(py_payload.py_topic)
+    Py_XDECREF(py_payload.py_args)
+    Py_XDECREF(py_payload.py_kwargs)
+    Py_XDECREF(py_payload.py_kwargs_aggregated)
+
+    c_ap_free(payload)
+
+
+cdef class MessagePayload:
+    def __init__(self, Topic topic, tuple args, dict kwargs):
+        self.header = c_evt_payload_new(topic, args, kwargs)
+        if not self.header:
+            raise MemoryError('Failed to allocate memory for evt_message_payload')
+        self.owner = True
+
+    def __dealloc__(self):
+        if not self.owner:
+            return
+
+        if self.header:
+            c_evt_payload_free(self.header)
+
+    @staticmethod
+    cdef MessagePayload c_from_header(evt_message_payload* payload, bint owner=False):
+        cdef MessagePayload instance = MessagePayload.__new__(MessagePayload)
+        instance.header = payload
+        instance.owner = owner
+        return instance
+
+    def __repr__(self):
+        if not self.header:
+            return '<MessagePayload uninitialized>'
+        if self.header.topic:
+            return f'<MessagePayload "{self.topic.value}">(seq_id={self.seq_id}, args={self.args}, kwargs={self.kwargs})'
+        return f'<MessagePayload NO_TOPIC>(seq_id={self.seq_id}, args={self.args}, kwargs={self.kwargs})'
+
+    property topic:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError('Uninitialized c payload')
+            if not self.header.args:
+                raise RuntimeError('Uninitialized python payload')
+            cdef evt_py_payload* py_payload = <evt_py_payload*> self.header.args
+            cdef PyObject* py_topic = py_payload.py_topic
+            if py_topic:
+                Py_XINCREF(py_topic)
+                return <Topic> py_topic
+            cdef evt_topic* topic = self.header.topic
+            if topic:
+                return Topic.c_from_header(topic, False)
+            return None
+
+    property args:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError('Uninitialized c payload')
+            if not self.header.args:
+                raise RuntimeError('Uninitialized python payload')
+            cdef evt_py_payload* py_payload = <evt_py_payload*> self.header.args
+            cdef PyObject* py_args = py_payload.py_args
+            if py_args:
+                Py_XINCREF(py_args)
+                return <tuple> py_args
+            return None
+
+    property kwargs:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError('Uninitialized c payload')
+            if not self.header.args:
+                raise RuntimeError('Uninitialized python payload')
+            cdef evt_py_payload* py_payload = <evt_py_payload*> self.header.args
+            cdef PyObject* py_kwargs = py_payload.py_kwargs
+            if py_kwargs:
+                Py_XINCREF(py_kwargs)
+                return <dict> py_kwargs
+            return None
+
+    property kwargs_with_topic:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError('Uninitialized c payload')
+            if not self.header.args:
+                raise RuntimeError('Uninitialized python payload')
+            cdef evt_py_payload* py_payload = <evt_py_payload*> self.header.args
+            cdef PyObject* py_kwargs_aggregated = py_payload.py_kwargs_aggregated
+            if py_kwargs_aggregated:
+                Py_XINCREF(py_kwargs_aggregated)
+                return <dict> py_kwargs_aggregated
+            return None
+
+    property seq_id:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError('Uninitialized c payload')
+            return self.header.seq_id
+
+        def __set__(self, uint64_t seq_id):
+            if not self.header:
+                raise RuntimeError('Uninitialized c payload')
+            self.header.seq_id = seq_id
+
+
+cdef inline bint py_callable_same(PyObject* a, PyObject* b):
+    if a == b:
+        return True
+
+    # Both are bound methods
+    cdef object fn_a = <object> a
+    cdef object fn_b = <object> b
+    if PyMethod_Check(fn_a) and PyMethod_Check(fn_b):
+        return PyMethod_GET_SELF(fn_a) == PyMethod_GET_SELF(fn_b) and PyMethod_GET_FUNCTION(fn_a) == PyMethod_GET_FUNCTION(fn_b)
+    return False
+
+
+cdef class EventHook:
+    def __cinit__(self, Topic topic, object logger=None):
+        self.header = c_evt_hook_new(topic.header, EE_HEAP_ALLOCATOR)
+        if not self.header:
+            raise MemoryError(f'Failed to allocate memory for {self.__class__.__name__}')
+        self.callables = NULL
+        self.topic = topic
+        self.logger = LOGGER.getChild(f'EventHook.{topic}') if logger is None else logger
+
+    def __dealloc__(self):
+        self.c_free_py_callable()
+        if self.header:
+            c_evt_hook_free(self.header)
+
+    @staticmethod
+    cdef inline void c_invoke_py_callable(evt_message_payload* payload, void* user_data) with gil:
+        cdef evt_py_callable* ctx = <evt_py_callable*> user_data
+        cdef bint with_topic = ctx.with_topic
+        cdef evt_py_payload* py_payload = <evt_py_payload*> payload.args
+
+        cdef PyObject* fn = ctx.fn
+        cdef PyObject* args = py_payload.py_args
+        cdef PyObject* kwargs = py_payload.py_kwargs_aggregated if with_topic else py_payload.py_kwargs
+        cdef PyObject* res = PyObject_Call(fn, args, kwargs)
+
+        if res:
+            Py_XDECREF(res)
+            return
+
+        # Fetch the current Python exception (steals references; clears the indicator)
+        cdef PyObject* etype = NULL
+        cdef PyObject* evalue = NULL
+        cdef PyObject* etrace = NULL
+        cdef object logger = <object> ctx.logger
+        cdef object formatted
+
+        PyErr_Fetch(&etype, &evalue, &etrace)
+        formatted = traceback.format_exception(<object> etype, (<object> evalue) if evalue else None, (<object> etrace) if etrace else None)
+        logger.error("".join(formatted))
+        Py_XDECREF(etype)
+        Py_XDECREF(evalue)
+        Py_XDECREF(etrace)
+        PyErr_Clear()
+
+    cdef inline evt_py_callable* c_add_py_callable(self, PyObject* py_callable, PyObject* logger, bint with_topic, bint deduplicate):
+        if not PyCallable_Check(py_callable):
+            raise ValueError('Callback handler must be callable')
+
+        cdef evt_py_callable* callable_frame = self.callables
+
+        # Walk list to detect duplicates and position at tail
+        cdef evt_py_callable* tail = NULL
+        while callable_frame:
+            if py_callable_same(callable_frame.fn, py_callable):
+                if deduplicate:
+                    return callable_frame
+                else:
+                    self.logger.warning(f'Handler {<object> py_callable} already registered in {self}. Adding again will be called multiple times when triggered.')
+            tail = callable_frame
+            callable_frame = callable_frame.next
+
+        # Allocate new node
+        callable_frame = <evt_py_callable*> c_ap_alloc(sizeof(evt_py_callable), EE_HEAP_ALLOCATOR)
+        if not callable_frame:
+            raise MemoryError('Failed to allocate memory for new evt_py_callable')
+
+        Py_XINCREF(logger)
+        Py_XINCREF(py_callable)
+
+        callable_frame.fn = py_callable
+        callable_frame.logger = logger
+        callable_frame.idx = self.header.n_callbacks
+        callable_frame.with_topic = with_topic
+
+        if tail:
+            tail.next = callable_frame
+        else:
+            self.callables = callable_frame
+
+        c_evt_hook_register_callback(
+            self.header,
+            <const void*> EventHook.c_invoke_py_callable,
+            evt_callback_type.EVT_CALLBACK_WITH_PAYLOAD_USERDATA,
+            <void*> callable_frame,
+            0
+        )
+        return callable_frame
+
+    cdef inline int c_remove_py_callable(self, PyObject* py_callable):
+        cdef evt_py_callable* curr = self.callables
+        cdef evt_py_callable* prior = NULL
+
+        while curr:
+            if py_callable_same(curr.fn, py_callable):
+                Py_XDECREF(curr.fn)
+                Py_XDECREF(curr.logger)
+                if prior:
+                    prior.next = curr.next
+                else:
+                    self.callables = curr.next
+                c_evt_hook_pop_callback(self.header, curr.idx)
+                prior = curr.next
+                while prior:
+                    prior.idx -= 1
+                    prior = prior.next
+                c_ap_free(curr)
+                return 1
+            prior = curr
+            curr = curr.next
+        return 0
+
+    cdef inline bint c_contains_py_callable(self, PyObject* py_callable):
+        cdef evt_py_callable* curr = self.callables
+
+        while curr:
+            if py_callable_same(curr.fn, py_callable):
+                return True
+            curr = curr.next
+        return False
+
+    cdef void c_free_py_callable(self):
+        cdef evt_py_callable* curr = self.callables
+        cdef evt_py_callable* next
+        while curr:
+            next = curr.next
+            Py_XDECREF(curr.fn)
+            Py_XDECREF(curr.logger)
+            c_evt_hook_pop_callback(self.header, 0)
+            c_ap_free(curr)
+            curr = next
+        self.callables = NULL
+
+    def __call__(self, MessagePayload msg):
+        c_evt_hook_invoke(self.header, msg.header)
+
+    def __iadd__(self, object py_callable):
+        self.add_handler(py_callable, None, True)
+        return self
+
+    def __isub__(self, object py_callable):
+        self.c_remove_py_callable(<PyObject*> py_callable)
+        return self
+
+    def __len__(self):
+        return self.header.n_callbacks
+
+    def __repr__(self):
+        if self.topic:
+            return f'<{self.__class__.__name__} "{self.topic.value}">(n={len(self)})'
+        return f'<{self.__class__.__name__} NO_TOPIC>(n={len(self)})'
+
+    def __iter__(self):
+        return self.handlers.__iter__()
+
+    def __contains__(self, object py_callable):
+        return self.c_contains_py_callable(<PyObject*> py_callable)
+
+    def trigger(self, MessagePayload msg):
+        c_evt_hook_invoke(self.header, msg.header)
+
+    def add_handler(self, object py_callable, object logger=None, bint deduplicate=False):
+        cdef object sig = inspect.signature(py_callable)
+        cdef object param
+        cdef bint with_topic = False
+
+        for param in sig.parameters.values():
+            if param.name == TOPIC_FIELD_NAME or param.kind == inspect.Parameter.VAR_KEYWORD:
+                with_topic = True
+                break
+
+        if logger is None:
+            logger = self.logger
+
+        self.c_add_py_callable(<PyObject*> py_callable, <PyObject*> logger, with_topic, deduplicate)
+
+    def remove_handler(self, object py_callable):
+        cdef int removed = self.c_remove_py_callable(<PyObject*> py_callable)
+        if not removed:
+            LOGGER.warning(f'{py_callable} not exist in {self} call stacks')
+
+    def clear(self):
+        self.c_free_py_callable()
+
+    property handlers:
+        def __get__(self):
+            cdef evt_py_callable* curr = self.callables
+            cdef list out = []
+            while curr:
+                out.append(dict(
+                    fn=<object> curr.fn,
+                    logger=<object> curr.logger,
+                    idx=curr.idx,
+                    with_topic=curr.with_topic
+                ))
+                Py_XINCREF(curr.fn)
+                Py_XINCREF(curr.logger)
+                curr = curr.next
+            return out
+
+
+cdef inline void c_hook_enter(evt_hook* hook, evt_hook_watcher_type watcher_type, evt_message_payload* payload, void* user_data) noexcept nogil:
+    cdef evt_hook_stats* stats = <evt_hook_stats*> user_data
+    stats.n_calls += 1
+    stats.ts_call_start = perf_counter()
+
+
+cdef inline void c_hook_exit(evt_hook* hook, evt_hook_watcher_type watcher_type, evt_message_payload* payload, void* user_data) noexcept nogil:
+    cdef evt_hook_stats* stats = <evt_hook_stats*> user_data
+    stats.ts_call_complete = perf_counter()
+    stats.elapsed_seconds += stats.ts_call_complete - stats.ts_call_start
+
+
+cdef class EventHookEx(EventHook):
+    def __cinit__(self, Topic topic, object logger=None):
+        c_evt_hook_add_watcher(self.header, c_hook_enter, <void*> &self.hook_stats, evt_hook_watcher_type.EVT_HOOK_WATCHER_PRE_INVOKED)
+        c_evt_hook_add_watcher(self.header, c_hook_exit, <void*> &self.hook_stats, evt_hook_watcher_type.EVT_HOOK_WATCHER_POST_INVOKED)
+
+    property stats:
+        def __get__(self):
+            cdef dict stats = {
+                'n_calls': self.hook_stats.n_calls,
+                'last_call_start': self.hook_stats.ts_call_start,
+                'last_call_complete': self.hook_stats.ts_call_complete,
+                'elapsed_seconds': self.hook_stats.elapsed_seconds
+            }
+            return stats
+
+
+cdef class EventTestToolkit:
+    """Relays internal C event-hook state to Python for test validation.
+
+    Exposes the raw ``evt_hook`` counters (callback and watcher arrays) and
+    the ``evt_py_callable`` linked list, which are internal C state not
+    exposed through the public Python API.
+
+    Note:
+        Test-only class. Not declared in any ``.pxd``; not part of the
+        public package API.
+    """
+
+    @staticmethod
+    def get_n_callbacks(EventHook hook) -> size_t:
+        """Number of C callbacks registered on the hook."""
+        return hook.header.n_callbacks
+
+    @staticmethod
+    def get_n_pre_watchers(EventHook hook) -> size_t:
+        """Number of pre-invoked watchers registered on the hook."""
+        return hook.header.n_pre_watchers
+
+    @staticmethod
+    def get_n_post_watchers(EventHook hook) -> size_t:
+        """Number of post-invoked watchers registered on the hook."""
+        return hook.header.n_post_watchers
+
+    @staticmethod
+    def get_callable_count(EventHook hook) -> size_t:
+        """Length of the Python-callable linked list."""
+        cdef evt_py_callable* curr = hook.callables
+        cdef size_t n = 0
+        while curr:
+            n += 1
+            curr = curr.next
+        return n
+
+    @staticmethod
+    def get_callable_with_topic(EventHook hook, size_t idx) -> bint:
+        """Whether the callable at ``idx`` is invoked with the topic kwarg."""
+        cdef evt_py_callable* curr = hook.callables
+        cdef size_t i = 0
+        while curr:
+            if i == idx:
+                return curr.with_topic
+            i += 1
+            curr = curr.next
+        raise IndexError(f'Index {idx} out of range!')
+
+    @staticmethod
+    def get_hook_topic_addr(EventHook hook) -> uintptr_t:
+        """Address of the C topic backing the hook."""
+        return <uintptr_t> hook.header.topic