Module timer 

FFI types and functions for time event handling.

The TimeEventHandler_API handed to Cython stores only a borrowed Py<PyAny>* (callback_ptr). To make sure the pointed-to Python object stays alive while any handler referencing it exists, we keep a single Arc<Py<PyAny>> per raw pointer in an internal registry together with a manual reference counter.

Why a registry instead of extra fields:

• The C ABI must remain struct { TimeEvent, char * } - adding bytes to the struct would break all generated headers.
• Arc<Py<..>> guarantees GIL-safe INC/DEC but cannot be represented in C. Storing it externally preserves layout while retaining safety.

Drop strategy:

1. Cloning a handler increments the per-pointer counter.
2. Dropping a handler decrements it; if the count hits zero we remove the entry then release the Arc under Python::attach. The drop happens outside the mutex guard to avoid dead-locking when Python finalisers re-enter the registry.

This design removes all manual INCREF/DECREF on callback_ptr, eliminates leaks, and is safe on any thread.

Structs

TimeEventHandler_API

FFI time event handler for Cython interoperability.

Functions

cleanup_callback_registry

dummy

registry_size

time_event_handler_drop

Drops a TimeEventHandler_API, releasing any Python callback reference.

time_event_new^⚠

Safety

time_event_to_cstr

Returns a TimeEvent as a C string pointer.