terom@39: """
terom@39:     Core `struct event` type.
terom@39: """
terom@39: 
terom@39: cimport qmsk.net.lib.event2.lib as lib
terom@39: 
terom@57: from qmsk.net.lib.event2.base cimport event_base
terom@57: 
terom@39: # internal helper method for handling timeout arguments
terom@39: cdef lib.timeval* build_timeout (lib.timeval *tv, object timeout = ?) except? <lib.timeval *>-1
terom@39: 
terom@39: cdef class event :
terom@39:     """
terom@39:         Create a new event object with the given parameters.
terom@39:         
terom@39:         An event tracks a single OS file descriptor with some set of events (EV_READ/EV_WRITE) and an optional timeout.
terom@39:         
terom@39:         An event is associated with some event_base, which handles the event mechanism.
terom@39:         
terom@39:         Arguments:
terom@39:             base        - event_base to use for this event
terom@39:             fd          - OS file descriptor to watch, or -1
terom@39:             events      - bitmask of EV_* flags that represents the events to wait for
terom@39: 
terom@50:         When the event fires, it will "call" this event object (see docs for __call__()).
terom@50: 
terom@50:         The lifetime of event objects is slightly non-trivial, in that they will actually hold a reference to
terom@50:         themselves while "active". In other words, .add() will aquire an internal reference, which will be released
terom@50:         before the __call__().
terom@52: 
terom@52:         XXX: propagate errors (including e.g. KeyboardInterrupt?) from __call__ to event_base.loop()?
terom@39:     """
terom@39: 
terom@57:     # reference to our supporting event_base to ensure we don't lose it
terom@57:     cdef readonly event_base base
terom@57: 
terom@39:     # the underlying event object
terom@39:     cdef lib.event *ev
terom@39: 
terom@50:     # slightly different meaning from libevent's "active", this is used to track our own refcount
terom@50:     cdef readonly bool alive
terom@50: 
terom@50:     # self-refcount scheme
terom@50:     cdef object _mark (self)
terom@50:     cdef object _unmark (self)
terom@50:     
terom@50:     # methods also used internally
terom@50:     cpdef pending (self, short mask = ?)