"""
    Core `struct event` type.
"""

cimport qmsk.net.lib.event2.lib as lib

# internal helper method for handling timeout arguments
cdef lib.timeval* build_timeout (lib.timeval *tv, object timeout = ?) except? <lib.timeval *>-1

cdef class event :
    """
        Create a new event object with the given parameters.
        
        An event tracks a single OS file descriptor with some set of events (EV_READ/EV_WRITE) and an optional timeout.
        
        An event is associated with some event_base, which handles the event mechanism.
        
        Arguments:
            base        - event_base to use for this event
            fd          - OS file descriptor to watch, or -1
            events      - bitmask of EV_* flags that represents the events to wait for

        When the event fires, it will "call" this event object (see docs for __call__()).

        The lifetime of event objects is slightly non-trivial, in that they will actually hold a reference to
        themselves while "active". In other words, .add() will aquire an internal reference, which will be released
        before the __call__().

        XXX: it might be better for refcounting if the event_base were to keep a reference to each event
        XXX: or if we kept a reference to the event_base? Might be even better

        XXX: propagate errors (including e.g. KeyboardInterrupt?) from __call__ to event_base.loop()?
    """

    # the underlying event object
    cdef lib.event *ev

    # slightly different meaning from libevent's "active", this is used to track our own refcount
    cdef readonly bool alive

    # self-refcount scheme
    cdef object _mark (self)
    cdef object _unmark (self)
    
    # methods also used internally
    cpdef pending (self, short mask = ?)