1

"""

     2

    Core `struct event_base` type

     3

"""

     4

     5

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

     6

     7

cdef class event_base :

     8

    """

     9

        An event_base stores the "global" state associated with events - it holds a set of events (pending/active/scheduled),

    10

        and uses some specific multiplexing method (select/poll/epoll/kqueue/etc) to drive these events.

    11

    14

    15

        Libevent has its own asynchronous signal-handling mechanism that is incompatible with Python's signal-handling

    16

        mechanism.

    17

    18

        Technical details:

    19

            Python's signal handlers will simply set a flag corresponding to the signal, and wait for

    20

            PyErr_CheckSignals to be run. Following this, libevent's epoll/select/etc() call will return EINTER - but

    21

            this will only cause libevent to check its own signal state, and continue running.

    22

    23

        To solve this, we register a "wakeup fd" in Python's signal handling system, whereby a byte is written to a

    24

        socket pair whenever python's signal handler runs. We then register an (internal) event for the other end of

    25

        this socketpair in the event_base, which then runs the python signal handlers from "inside" of .loop(),

    26

        propagating exceptions out of .loop() - this solution is more or less equivalent to how libevent's signal

    27

        handling works.

    28

    29

        This means that python's default signals and any other signals added using the signal module continue to work

    30

        at the cost of some additional complexity, but any libevent signal-events also work as well :)

    31

    35

        thread and sub-threads, since the python signal handling mechanism only works in the main thread.

    36

    38

    41

    """

    42

    43

    # the underlying ev_base object

    44

    cdef lib.event_base *ev_base

    45

    46

    # internal event for PySignal wakeups

    47

    cdef lib.event *ev_pysignal

    48