"""
    Core `struct event_base` type
"""

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

cdef class event_base :
    """
        An event_base stores the "global" state associated with events - it holds a set of events (pending/active/scheduled),
        and uses some specific multiplexing method (select/poll/epoll/kqueue/etc) to drive these events.
        
        Constructs a new event_base with default parameters.

        XXX: you must keep a reference to the event_base around yourself!
        XXX: what happens to events once we are destructed?
        
        Libevent has its own asynchronous signal-handling mechanism that is incompatible with Python's signal-handling
        mechanism.
        
        Technical details:
            Python's signal handlers will simply set a flag corresponding to the signal, and wait for
            PyErr_CheckSignals to be run. Following this, libevent's epoll/select/etc() call will return EINTER - but
            this will only cause libevent to check its own signal state, and continue running.

        To solve this, we register a "wakeup fd" in Python's signal handling system, whereby a byte is written to a
        socket pair whenever python's signal handler runs. We then register an (internal) event for the other end of
        this socketpair in the event_base, which then runs the python signal handlers from "inside" of .loop(),
        propagating exceptions out of .loop() - this solution is more or less equivalent to how libevent's signal
        handling works.
        
        This means that python's default signals and any other signals added using the signal module continue to work
        at the cost of some additional complexity, but any libevent signal-events also work as well :)
        
        XXX: currently, you can only have one event_base at a time - there should be separate types used for the main
        thread and sub-threads, since the python signal handling mechanism only works in the main thread.

        XXX: the propagate-exceptions doesn't actually work either, it just aborts the event loop :)

        XXX: add support for event_config!
        XXX: add support for event_base_priority_init!

    """
    
    # the underlying ev_base object
    cdef lib.event_base *ev_base

    # internal event for PySignal wakeups
    cdef lib.event *ev_pysignal