PyEventEngine 0.6.2__cp315-cp315t-win_amd64.whl

event_engine/capi/c_engine.pyx

@@ -0,0 +1,673 @@
+from threading import Thread
+
+from cpython.datetime cimport timedelta
+from cpython.object cimport PyObject
+from cpython.ref cimport Py_INCREF, Py_XDECREF, Py_XINCREF
+from cpython.time cimport perf_counter
+from cpython.unicode cimport PyUnicode_FromStringAndSize
+
+from cbase.bytemap.c_bytemap cimport bytemap_ret_code, bytemap, bytemap_entry, c_bytemap_new, c_bytemap_clear, c_bytemap_free, c_bytemap_get, c_bytemap_set, c_bytemap_pop, c_bytemap_entry_value
+
+from .c_event cimport EMPTY_ARGS, MessagePayload, c_evt_hook_invoke, c_evt_payload_free, c_evt_payload_new, evt_py_payload
+from .c_topic cimport Topic, c_topic_match_bool
+from ..base.c_allocator_protocol cimport EE_HEAP_ALLOCATOR
+from ..base import LOGGER
+
+LOGGER = LOGGER.getChild('Engine')
+
+
+class Full(Exception):
+    pass
+
+
+class Empty(Exception):
+    pass
+
+
+cdef class EventEngine:
+    def __cinit__(self, size_t capacity=DEFAULT_MQ_CAPACITY, object logger=None):
+        self.logger = LOGGER.getChild(f'EventEngine') if logger is None else logger
+        cdef allocator_protocol* allocator = EE_HEAP_ALLOCATOR
+
+        self.mq = c_mq_new(capacity, NULL, allocator)
+        if not self.mq:
+            raise MemoryError(f'Failed to allocate MessageQueue for {self.__class__.__name__}.')
+
+        self.exact_topic_hooks = c_bytemap_new(0, NULL)
+        if not self.exact_topic_hooks:
+            c_mq_free(self.mq)
+            self.mq = NULL
+            raise MemoryError(f'Failed to allocate exact_topic_hooks for {self.__class__.__name__}.')
+
+        self.generic_topic_hooks = c_bytemap_new(0, NULL)
+        if not self.generic_topic_hooks:
+            c_mq_free(self.mq)
+            c_bytemap_free(self.exact_topic_hooks)
+            self.mq = NULL
+            raise MemoryError(f'Failed to allocate generic_topic_hooks for {self.__class__.__name__}.')
+
+        self.seq_id = 0
+
+    def __dealloc__(self):
+        if self.mq:
+            c_mq_free(self.mq)
+            self.mq = NULL
+
+        if self.exact_topic_hooks:
+            c_bytemap_free(self.exact_topic_hooks)
+            self.exact_topic_hooks = NULL
+
+        if self.generic_topic_hooks:
+            c_bytemap_free(self.generic_topic_hooks)
+            self.generic_topic_hooks = NULL
+
+    cdef inline void c_loop(self):
+        if not self.mq:
+            raise RuntimeError('Not initialized!')
+
+        cdef evt_message_payload* msg = NULL
+        cdef evt_py_payload* py_payload = NULL
+        cdef message_queue* mq = self.mq
+        cdef int ret_code
+
+        while self.active:
+            # Step 1: Await message
+            with nogil:
+                ret_code = c_mq_get_hybrid(mq, &msg, DEFAULT_MQ_SPIN_LIMIT, DEFAULT_MQ_TIMEOUT_SECONDS)
+                if ret_code != 0:
+                    continue
+
+            # Trigger message callbacks
+            self.c_trigger(msg)
+
+            # Clean up the message payload
+            c_evt_payload_free(msg)
+
+    cdef inline evt_message_payload* c_get(self, bint block, size_t max_spin, double timeout):
+        cdef evt_message_payload* msg = NULL
+        cdef int ret_code
+        if block:
+            ret_code = c_mq_get_hybrid(self.mq, &msg, max_spin, timeout)
+        else:
+            ret_code = c_mq_get(self.mq, &msg)
+
+        if ret_code != 0:
+            return NULL
+        return msg
+
+    cdef inline int c_publish(self, Topic topic, tuple args, dict kwargs, bint block, size_t max_spin, double timeout):
+        if not topic.header.is_exact:
+            raise ValueError('Topic must be all of exact parts')
+
+        # Step 0: Request payload buffer (MUST be done with GIL held - allocator is NOT thread-safe)
+        cdef evt_message_payload* payload = c_evt_payload_new(topic, args, kwargs)
+
+        # Step 1: Assembling payload (MUST be done with GIL held - touching Python objects)
+        payload.seq_id = self.seq_id
+        self.seq_id += 1
+
+        # Step 2: Send the payload (can be done without GIL - queue is thread-safe)
+        cdef int ret_code
+        with nogil:
+            if block:
+                ret_code = c_mq_put_hybrid(self.mq, payload, max_spin, timeout)
+            else:
+                ret_code = c_mq_put(self.mq, payload)
+
+        # Step 4: Handle failure case (undo increfs and free payload)
+        if not ret_code:
+            return ret_code
+
+        self.seq_id -= 1
+        c_evt_payload_free(payload)
+        return ret_code
+
+    cdef inline void c_trigger(self, evt_message_payload* msg):
+        cdef evt_topic* msg_topic = msg.topic
+        # Step 1: Match exact_topic_hooks
+        cdef PyObject* hook_ptr = NULL
+        cdef EventHook event_hook
+
+        cdef int ret_code = c_bytemap_get(self.exact_topic_hooks, msg_topic.key, msg_topic.key_len, <void**> &hook_ptr)
+        if hook_ptr:
+            event_hook = <EventHook> hook_ptr
+            c_evt_hook_invoke(event_hook.header, msg)
+
+        # Step 2: Match generic_topic_hooks
+        cdef bytemap_entry* entry = self.generic_topic_hooks.first
+        cdef int is_matched
+        while entry:
+            hook_ptr = <PyObject*> c_bytemap_entry_value(entry)
+            if not hook_ptr:
+                entry = entry.next
+                continue
+            event_hook = <EventHook> <PyObject*> hook_ptr
+            is_matched = c_topic_match_bool(event_hook.topic.header, msg_topic)
+            if is_matched:
+                c_evt_hook_invoke(event_hook.header, msg)
+            entry = entry.next
+
+    cdef inline EventHook c_get_hook(self, Topic topic):
+        cdef evt_topic* topic_ptr = topic.header
+        cdef PyObject* hook_ptr = NULL
+        cdef EventHook event_hook
+        cdef bytemap* hook_map
+
+        if topic_ptr.is_exact:
+            hook_map = self.exact_topic_hooks
+        else:
+            hook_map = self.generic_topic_hooks
+
+        cdef int ret_code = c_bytemap_get(hook_map, topic_ptr.key, topic_ptr.key_len, <void**> &hook_ptr)
+        if ret_code == bytemap_ret_code.BYTEMAP_ERR_NOT_FOUND:
+            raise KeyError(f'No EventHook registered for {topic.value}')
+        event_hook = <EventHook> hook_ptr
+        Py_XINCREF(hook_ptr)
+        return event_hook
+
+    cdef inline void c_register_hook(self, EventHook hook):
+        cdef evt_topic* topic_ptr = hook.topic.header
+        cdef PyObject* existing_hook_ptr = NULL
+        cdef bytemap* hook_map
+
+        if topic_ptr.is_exact:
+            hook_map = self.exact_topic_hooks
+        else:
+            hook_map = self.generic_topic_hooks
+
+        cdef int ret_code = c_bytemap_get(hook_map, topic_ptr.key, topic_ptr.key_len, <void**> &existing_hook_ptr)
+        if existing_hook_ptr and existing_hook_ptr != <PyObject*> hook:
+            raise KeyError(f'Another EventHook already registered for {hook.topic.value}')
+        ret_code = c_bytemap_set(hook_map, topic_ptr.key, topic_ptr.key_len, <void*> <PyObject*> hook, NULL)
+        Py_INCREF(hook)
+
+    cdef inline EventHook c_unregister_hook(self, Topic topic):
+        cdef evt_topic* topic_ptr = topic.header
+        cdef PyObject* existing_hook_ptr = NULL
+        cdef bytemap* hook_map
+
+        if topic_ptr.is_exact:
+            hook_map = self.exact_topic_hooks
+        else:
+            hook_map = self.generic_topic_hooks
+        cdef int ret_code = c_bytemap_pop(hook_map, <char*> topic_ptr.key, topic_ptr.key_len, <void**> &existing_hook_ptr)
+        if not existing_hook_ptr:
+            raise KeyError(f'No EventHook registered for {topic.value}')
+        cdef EventHook hook = <EventHook> existing_hook_ptr
+        Py_XDECREF(<PyObject*> hook)
+        return hook
+
+    cdef inline void c_register_handler(self, Topic topic, object py_callable, bint deduplicate):
+        cdef evt_topic* topic_ptr = topic.header
+        cdef PyObject* hook_ptr = NULL
+        cdef EventHook event_hook
+        cdef bytemap* hook_map
+
+        if topic_ptr.is_exact:
+            hook_map = self.exact_topic_hooks
+        else:
+            hook_map = self.generic_topic_hooks
+
+        cdef int ret_code = c_bytemap_get(hook_map, topic_ptr.key, topic_ptr.key_len, <void**> &hook_ptr)
+        if ret_code == bytemap_ret_code.BYTEMAP_ERR_NOT_FOUND:
+            event_hook = EventHook.__new__(EventHook, topic, self.logger)
+            c_bytemap_set(hook_map, topic_ptr.key, topic_ptr.key_len, <void*> <PyObject*> event_hook, NULL)
+            Py_INCREF(event_hook)
+        elif not hook_ptr:
+            raise BufferError(f'Corrected buffer, invalid registered event hook.')
+        else:
+            event_hook = <EventHook> hook_ptr
+        event_hook.add_handler(py_callable, None, deduplicate)
+
+    cdef inline void c_unregister_handler(self, Topic topic, object py_callable):
+        cdef evt_topic* topic_ptr = topic.header
+        cdef PyObject* hook_ptr = NULL
+        cdef EventHook event_hook
+        cdef bytemap* hook_map
+
+        if topic_ptr.is_exact:
+            hook_map = self.exact_topic_hooks
+        else:
+            hook_map = self.generic_topic_hooks
+
+        cdef int ret_code = c_bytemap_get(hook_map, topic_ptr.key, topic_ptr.key_len, <void**> &hook_ptr)
+        if ret_code == bytemap_ret_code.BYTEMAP_ERR_NOT_FOUND:
+            LOGGER.error(f'No EventHook registered for "{topic.value}"')
+            return
+        event_hook = <EventHook> hook_ptr
+        event_hook.remove_handler(py_callable)
+        if len(event_hook) == 0:
+            c_bytemap_pop(hook_map, topic_ptr.key, topic_ptr.key_len, NULL)
+            Py_XDECREF(<PyObject*> event_hook)
+
+    cdef inline void c_clear(self):
+        cdef bytemap_entry* entry
+        cdef EventHook event_hook
+
+        # Clear exact_topic_hooks
+        entry = self.exact_topic_hooks.first
+        while entry:
+            if c_bytemap_entry_value(entry):
+                event_hook = <EventHook> <PyObject*> c_bytemap_entry_value(entry)
+                event_hook.clear()
+                Py_XDECREF(<PyObject*> event_hook)
+            entry = entry.next
+        c_bytemap_clear(self.exact_topic_hooks)
+
+        # Clear generic_topic_hooks
+        entry = self.generic_topic_hooks.first
+        while entry:
+            if c_bytemap_entry_value(entry):
+                event_hook = <EventHook> <PyObject*> c_bytemap_entry_value(entry)
+                event_hook.clear()
+                Py_XDECREF(<PyObject*> event_hook)
+            entry = entry.next
+        c_bytemap_clear(self.generic_topic_hooks)
+
+    # --- Python Interfaces---
+
+    def __len__(self):
+        count = 0
+        entry = self.exact_topic_hooks.first
+        while entry:
+            if c_bytemap_entry_value(entry):
+                count += 1
+            entry = entry.next
+        entry = self.generic_topic_hooks.first
+        while entry:
+            if c_bytemap_entry_value(entry):
+                count += 1
+            entry = entry.next
+        return count
+
+    def __repr__(self):
+        return f'<{self.__class__.__name__} {"active" if self.active else "idle"}>(capacity={self.capacity})'
+
+    def __getitem__(self, Topic topic) -> list[EventHook]:
+        cdef list out = []
+        cdef evt_topic* topic_ptr = topic.header
+        cdef PyObject* hook_ptr = NULL
+        cdef EventHook event_hook
+
+        cdef int ret_code = c_bytemap_get(self.exact_topic_hooks, topic_ptr.key, topic_ptr.key_len, <void**> &hook_ptr)
+        if hook_ptr:
+            event_hook = <EventHook> hook_ptr
+            Py_XINCREF(hook_ptr)
+            out.append(event_hook)
+
+        cdef bytemap_entry* entry = self.generic_topic_hooks.first
+        cdef int is_matched
+        while entry:
+            hook_ptr = <PyObject*> c_bytemap_entry_value(entry)
+            if not hook_ptr:
+                entry = entry.next
+                continue
+            event_hook = <EventHook> hook_ptr
+            is_matched = c_topic_match_bool(event_hook.topic.header, topic_ptr)
+            if is_matched:
+                Py_XINCREF(hook_ptr)
+                out.append(event_hook)
+            entry = entry.next
+        return out
+
+    def activate(self):
+        self.active = True
+
+    def deactivate(self):
+        self.active = False
+
+    def run(self):
+        self.c_loop()
+
+    def start(self):
+        if self.active:
+            self.logger.warning(f'{self} already started!')
+            return
+        self.active = True
+        self.engine = Thread(target=self.run, name='EventEngine')
+        self.engine.start()
+        self.logger.info(f'{self} started.')
+
+    def stop(self) -> None:
+        if not self.active:
+            self.logger.warning('EventEngine already stopped!')
+            return
+
+        self.active = False
+        self.engine.join()
+
+    def clear(self) -> None:
+        if self.active:
+            self.logger.error('EventEngine must be stopped before cleared!')
+            return
+
+        self.c_clear()
+
+    def get(self, bint block=True, size_t max_spin=DEFAULT_MQ_SPIN_LIMIT, double timeout=0.0) -> MessagePayload:
+        cdef evt_message_payload* msg = self.c_get(block, max_spin, timeout)
+        if not msg:
+            raise Empty()
+        cdef MessagePayload payload = MessagePayload.c_from_header(msg, True)
+        return payload
+
+    def put(self, Topic topic, *args, bint block=True, size_t max_spin=DEFAULT_MQ_SPIN_LIMIT, double timeout=0.0, **kwargs):
+        cdef int ret_code = self.c_publish(topic, args, kwargs, block, max_spin, timeout)
+        if ret_code:
+            raise Full()
+
+    def publish(self, Topic topic, tuple args, dict kwargs, bint block=True, size_t max_spin=DEFAULT_MQ_SPIN_LIMIT, double timeout=0.0):
+        cdef int ret_code = self.c_publish(topic, args, kwargs, block, max_spin, timeout)
+        if ret_code:
+            raise Full()
+
+    def get_hook(self, Topic topic):
+        return self.c_get_hook(topic)
+
+    def register_hook(self, EventHook hook):
+        self.c_register_hook(hook)
+
+    def unregister_hook(self, Topic topic) -> EventHook:
+        return self.c_unregister_hook(topic)
+
+    def register_handler(self, Topic topic, object handler, bint deduplicate=False):
+        self.c_register_handler(topic, handler, deduplicate)
+
+    def unregister_handler(self, Topic topic, object handler):
+        self.c_unregister_handler(topic, handler)
+
+    def event_hooks(self):
+        entry = self.exact_topic_hooks.first
+        while entry:
+            if c_bytemap_entry_value(entry):
+                yield <EventHook> <PyObject*> c_bytemap_entry_value(entry)
+            entry = entry.next
+        entry = self.generic_topic_hooks.first
+        while entry:
+            if c_bytemap_entry_value(entry):
+                yield <EventHook> <PyObject*> c_bytemap_entry_value(entry)
+            entry = entry.next
+
+    def topics(self):
+        entry = self.exact_topic_hooks.first
+        while entry:
+            if c_bytemap_entry_value(entry):
+                yield (<EventHook> <PyObject*> c_bytemap_entry_value(entry)).topic
+            entry = entry.next
+        entry = self.generic_topic_hooks.first
+        while entry:
+            if c_bytemap_entry_value(entry):
+                yield (<EventHook> <PyObject*> c_bytemap_entry_value(entry)).topic
+            entry = entry.next
+
+    def items(self):
+        entry = self.exact_topic_hooks.first
+        while entry:
+            if c_bytemap_entry_value(entry):
+                hook = <EventHook> <PyObject*> c_bytemap_entry_value(entry)
+                yield (hook.topic, hook)
+            entry = entry.next
+        entry = self.generic_topic_hooks.first
+        while entry:
+            if c_bytemap_entry_value(entry):
+                hook = <EventHook> <PyObject*> c_bytemap_entry_value(entry)
+                yield (hook.topic, hook)
+            entry = entry.next
+
+    property capacity:
+        def __get__(self):
+            return self.mq.capacity
+
+    property occupied:
+        def __get__(self):
+            return c_mq_occupied(self.mq)
+
+    property exact_topic_hook_map:
+        def __get__(self):
+            cdef dict out = {}
+            cdef bytemap_entry* entry = self.exact_topic_hooks.first
+            cdef str topic_str
+            cdef EventHook event_hook
+            while entry:
+                topic_str = PyUnicode_FromStringAndSize(entry.key, entry.key_length)
+                event_hook = <EventHook> <PyObject*> c_bytemap_entry_value(entry)
+                entry = entry.next
+                Py_XINCREF(<PyObject*> event_hook)
+                out[Topic(topic_str)] = event_hook
+            return out
+
+    property generic_topic_hook_map:
+        def __get__(self):
+            cdef dict out = {}
+            cdef bytemap_entry* entry = self.generic_topic_hooks.first
+            cdef str topic_str
+            cdef EventHook event_hook
+            while entry:
+                topic_str = PyUnicode_FromStringAndSize(entry.key, entry.key_length)
+                event_hook = <EventHook> <PyObject*> c_bytemap_entry_value(entry)
+                entry = entry.next
+                Py_XINCREF(<PyObject*> event_hook)
+                out[Topic(topic_str)] = event_hook
+            return out
+
+
+cdef class EventEngineEx(EventEngine):
+    def __cinit__(self, size_t capacity=DEFAULT_MQ_CAPACITY, object logger=None):
+        self.timer = {}
+
+    cdef inline void c_timer_loop(self, double interval, Topic topic, datetime activate_time):
+        from time import sleep
+        cdef datetime scheduled_time
+
+        if activate_time is None:
+            scheduled_time = datetime.now()
+        else:
+            scheduled_time = activate_time
+
+        cdef dict kwargs = {'interval': interval, 'trigger_time': scheduled_time}
+
+        while self.active:
+            sleep_time = (scheduled_time - datetime.now()).total_seconds()
+
+            if sleep_time > 0:
+                sleep(sleep_time)
+            self.c_publish(topic, EMPTY_ARGS, kwargs, True, DEFAULT_MQ_SPIN_LIMIT, 0.0)
+
+            while scheduled_time < datetime.now():
+                scheduled_time += timedelta(seconds=interval)
+            kwargs['trigger_time'] = scheduled_time
+
+    cdef inline void c_minute_timer_loop(self, Topic topic):
+        from time import time, sleep
+        cdef double t, scheduled_time, next_time, sleep_time
+        cdef dict kwargs = {'interval': 60}
+
+        while self.active:
+            t = time()
+            scheduled_time = t // 60 * 60
+            next_time = scheduled_time + 60
+            sleep_time = next_time - t
+            sleep(sleep_time)
+            kwargs['timestamp'] = scheduled_time
+            self.c_publish(topic, EMPTY_ARGS, kwargs, True, DEFAULT_MQ_SPIN_LIMIT, 0.0)
+
+    cdef inline void c_second_timer_loop(self, Topic topic):
+        from time import time, sleep
+        cdef double t, scheduled_time, next_time, sleep_time
+        cdef dict kwargs = {'interval': 1}
+
+        while self.active:
+            t = time()
+            scheduled_time = t // 1
+            next_time = scheduled_time + 1
+            sleep_time = next_time - t
+            sleep(sleep_time)
+            kwargs['timestamp'] = scheduled_time
+            self.c_publish(topic, EMPTY_ARGS, kwargs, True, DEFAULT_MQ_SPIN_LIMIT, 0.0)
+
+    # --- Python Interfaces ---
+
+    def __repr__(self):
+        return f'<{self.__class__.__name__} {"active" if self.active else "idle"}>(capacity={self.capacity}, timers={list(self.timer.keys())})'
+
+    def run_timer(self, double interval, Topic topic, datetime activate_time=None):
+        if not self.active:
+            raise RuntimeError('EventEngine must be started before getting timer!')
+        self.c_timer_loop(interval, topic, activate_time)
+
+    def minute_timer(self, Topic topic):
+        if not self.active:
+            raise RuntimeError('EventEngine must be started before getting timer!')
+        self.c_minute_timer_loop(topic)
+
+    def second_timer(self, Topic topic):
+        if not self.active:
+            raise RuntimeError('EventEngine must be started before getting timer!')
+        self.c_second_timer_loop(topic)
+
+    def get_timer(self, double interval, datetime activate_time=None) -> Topic:
+        if not self.active:
+            raise RuntimeError('EventEngine must be started before getting timer!')
+
+        if interval == 1:
+            topic = Topic('EventEngine.Internal.Timer.Second')
+            timer = Thread(target=self.second_timer, kwargs={'topic': topic})
+        elif interval == 60:
+            topic = Topic('EventEngine.Internal.Timer.Minute')
+            timer = Thread(target=self.minute_timer, kwargs={'topic': topic})
+        else:
+            topic = Topic.join(['EventEngine', 'Internal', 'Timer', str(interval)])
+            timer = Thread(target=self.run_timer, kwargs={'interval': interval, 'topic': topic, 'activate_time': activate_time})
+
+        if interval not in self.timer:
+            self.timer[interval] = timer
+            timer.start()
+        else:
+            if activate_time is not None:
+                self.logger.debug(f'Timer thread with interval [{timedelta(seconds=interval)}] already initialized! Argument [activate_time] takes no effect!')
+
+        return topic
+
+    def stop(self) -> None:
+        super().stop()
+
+        for timer in self.timer.values():
+            timer.join()
+
+    def clear(self) -> None:
+        super().clear()
+
+        for t in self.timer.values():
+            t.join(timeout=0)
+        self.timer.clear()
+
+
+cdef class EngineTestToolkit:
+    """Relays internal C message-queue / hook-map state to Python for test validation.
+
+    Exposes the raw ``message_queue`` bookkeeping (head/tail/count/capacity),
+    the exact/generic hook bytemap contents, and a raw C message-queue
+    micro-benchmark. These internals are deliberately not part of the public
+    Python API, but are needed to verify queue-state transitions and to
+    measure the C-level hot path without Python overhead.
+
+    Note:
+        Test-only class. Not declared in any ``.pxd``; not part of the
+        public package API.
+    """
+
+    @staticmethod
+    def get_mq_capacity(EventEngine engine) -> size_t:
+        """Capacity of the engine's C message queue."""
+        return engine.mq.capacity
+
+    @staticmethod
+    def get_mq_head(EventEngine engine) -> size_t:
+        """Head index of the engine's C message queue."""
+        return engine.mq.head
+
+    @staticmethod
+    def get_mq_tail(EventEngine engine) -> size_t:
+        """Tail index of the engine's C message queue."""
+        return engine.mq.tail
+
+    @staticmethod
+    def get_mq_count(EventEngine engine) -> size_t:
+        """Occupancy counter of the engine's C message queue."""
+        return engine.mq.count
+
+    @staticmethod
+    def get_exact_hook_map_size(EventEngine engine) -> size_t:
+        """Number of entries in the exact-topic hook bytemap."""
+        cdef bytemap_entry* entry = engine.exact_topic_hooks.first
+        cdef size_t n = 0
+        while entry:
+            n += 1
+            entry = entry.next
+        return n
+
+    @staticmethod
+    def get_generic_hook_map_size(EventEngine engine) -> size_t:
+        """Number of entries in the generic-topic hook bytemap."""
+        cdef bytemap_entry* entry = engine.generic_topic_hooks.first
+        cdef size_t n = 0
+        while entry:
+            n += 1
+            entry = entry.next
+        return n
+
+    @staticmethod
+    def get_exact_hook_map_keys(EventEngine engine) -> list:
+        """Keys of all entries in the exact-topic hook bytemap."""
+        cdef list out = []
+        cdef bytemap_entry* entry = engine.exact_topic_hooks.first
+        while entry:
+            out.append(PyUnicode_FromStringAndSize(entry.key, entry.key_length))
+            entry = entry.next
+        return out
+
+    @staticmethod
+    def get_generic_hook_map_keys(EventEngine engine) -> list:
+        """Keys of all entries in the generic-topic hook bytemap."""
+        cdef list out = []
+        cdef bytemap_entry* entry = engine.generic_topic_hooks.first
+        while entry:
+            out.append(PyUnicode_FromStringAndSize(entry.key, entry.key_length))
+            entry = entry.next
+        return out
+
+    @staticmethod
+    def bench_mq_put_get(size_t n, size_t capacity=DEFAULT_MQ_CAPACITY) -> float:
+        """Average seconds per put/get round trip on a raw C message queue.
+
+        Allocates a standalone ``message_queue`` and a single payload, then
+        times ``n`` put/get cycles on the bare C API — no engine, no Python
+        dispatch, no handler invocation. Returns seconds per operation.
+
+        Args:
+            n: Number of put/get round trips to time.
+            capacity: Capacity of the raw message queue.
+
+        Returns:
+            Average elapsed seconds per round trip.
+        """
+        cdef message_queue* mq = c_mq_new(capacity, NULL, EE_HEAP_ALLOCATOR)
+        if not mq:
+            raise MemoryError('Failed to allocate message queue for benchmark')
+
+        cdef Topic topic = Topic('bench.mq.topic')
+        cdef evt_message_payload* payload = c_evt_payload_new(topic, EMPTY_ARGS, {})
+        if not payload:
+            c_mq_free(mq)
+            raise MemoryError('Failed to allocate payload for benchmark')
+
+        cdef double t0 = perf_counter()
+        cdef size_t i
+        cdef evt_message_payload* out = NULL
+        for i in range(n):
+            c_mq_put(mq, payload)
+            c_mq_get(mq, &out)
+        cdef double elapsed = perf_counter() - t0
+
+        c_evt_payload_free(payload)
+        c_mq_free(mq)
+        return elapsed / n