libvirt/docs/kbase/internals/qemu-event-handlers.rst

===================
QEMU event handlers
===================

This is a short description of how an example qemu event can be used
to trigger handler code that is called from the context of a worker
thread, rather than directly from the event thread (which should
itself never block, and can't do things like send qemu monitor
commands, etc).

In this case (the ``NIC_RX_FILTER_CHANGED`` event) the event is handled by
calling a qemu monitor command to get the current RX filter state,
then executing ioctls/sending netlink messages on the host in response
to changes in that filter state. This event is *not* propagated to the
libvirt API (but if someone wants to add details of how to handle that
to the end of this document, please do!).

Hopefully this narration will be helpful when adding handlers for
other qemu events in the future.

QEMU monitor events
-------------------

Any event emitted by qemu is received by
``qemu_monitor_json.c:qemuMonitorJSONIOProcessEvent()``. It looks up the
event by name in the table ``eventHandlers`` (in the same file), which
should have an entry like this for each event that libvirt
understands::

    { "NIC_RX_FILTER_CHANGED", qemuMonitorJSONHandleNicRxFilterChanged, },

NB: This table is searched with bsearch, so it *must* be alphabetically sorted.

``qemuMonitorJSONIOProcessEvent`` calls the function listed in
``eventHandlers``, e.g.::

   qemu_monitor_json.c:qemuMonitorJSONHandleNicRxFilterChanged()

which extracts any required data from the JSON ("name" in this case),
and calls::

   qemu_monitor.c:qemuMonitorEmitNicRxFilterChanged()

which uses ``QEMU_MONITOR_CALLBACK()`` to call
``mon->cb->domainNicRxFilterChanged()``. ``domainNicRxFilterChanged`` is one
in a list of function pointers in ``qemu_process.c:monitorCallbacks``. For
our example, it has been set to::

   qemuProcessHandleNicRxFilterChanged()

This function allocates a ``qemuProcessEvent`` object, and queues an event
named ``QEMU_PROCESS_EVENT_NIC_RX_FILTER_CHANGED`` (you'll want to add an
enum to ``qemu_domain.h:qemuProcessEventType`` for your event) for a
worker thread to handle.

(Everything up to this point has happened in the context of the thread
that is reading events from qemu, so it should do as little as
possible, never block, and never call back into the qemu
monitor. Everything after this is handled in the context of a worker
thread, so it has more freedom to make qemu monitor calls and blocking
system calls on the host.)

When the worker thread gets the event, it calls::

   qemuProcessEventHandler()

which switches on the eventType (in our example,
``QEMU_PROCESS_EVENT_NIC_RX_FILTER_CHANGED``) and decides to call::

   processNicRxFilterChangedEvent()

and *that* is where the actual work will be done (and any
event-specific memory allocated during ``qemuProcessHandleXXX()`` will be
freed). Note that this function must do proper refcounting of the
domain object, and assure that the domain is still active prior to
performing any operations - it is possible that the domain could have
been destroyed between the time the event was received and the time
that it is processed, and it is also possible that the domain could be
destroyed *during* the event processing if it doesn't get properly
referenced by the handler.