mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-10-31 02:13:27 +00:00
e886274234
The images are referenced from '../images/' but the document is two layers deep thus '../../images' needs to be used Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
85 lines
3.5 KiB
ReStructuredText
85 lines
3.5 KiB
ReStructuredText
====================
|
|
Libvirt's event loop
|
|
====================
|
|
|
|
.. contents::
|
|
|
|
This page describes the event loop approach used in libvirt. Both server and
|
|
client.
|
|
|
|
Event driven programming
|
|
------------------------
|
|
|
|
Traditionally, a program simply ran once, then terminated. This type of program
|
|
was very common in the early days of computing, and lacked any form of user
|
|
interactivity. This is still used frequently, particularly in small one purpose
|
|
programs.
|
|
|
|
However, that approach is not suitable for all the types of applications. For
|
|
instance graphical applications spend most of their run time waiting for an
|
|
input from user. Only after it happened (in our example a button was clicked, a
|
|
key pressed, etc.) an event is generated to which they respond by executing
|
|
desired function. If generalized, this is how many long running programs
|
|
(daemons) work. Even those who are not waiting for direct user input and have no
|
|
graphical interface. Such as Libvirt.
|
|
|
|
.. image:: ../../images/event_loop_simple.png
|
|
:alt: event loop
|
|
|
|
In Libvirt this approach is used in combination with ``poll(2)`` as all the
|
|
communication with its clients (and domains it manages too) happens through
|
|
sockets. Therefore whenever new client connects, it is given exclusive file
|
|
descriptor which is then watched for incoming events, e.g. messages.
|
|
|
|
The event loop API
|
|
------------------
|
|
|
|
To work with event loop from our code we have plenty of APIs.
|
|
|
|
- ``virEventAddHandle``: Registers a callback for monitoring file handle
|
|
events.
|
|
- ``virEventUpdateHandle``: Change set of events monitored file handle is being
|
|
watched for.
|
|
- ``virEventRemoveHandle``: Unregisters previously registered file handle so
|
|
that it is no longer monitored for any events.
|
|
- ``virEventAddTimeout``: Registers a callback for timer event.
|
|
- ``virEventUpdateTimeout``: Changes frequency for a timer.
|
|
- ``virEventRemoveTimeout``: Unregisters a timer.
|
|
|
|
For more information on these APIs continue reading
|
|
`here <../../html/libvirt-libvirt-event.html>`__.
|
|
|
|
Worker pool
|
|
-----------
|
|
|
|
Looking back at the image above we can see one big limitation. While processing
|
|
a message event loop is blocked and for an outside observer unresponsive. This
|
|
is not acceptable for Libvirt. Therefore we have came up with the following
|
|
solution.
|
|
|
|
.. image:: ../../images/event_loop_worker.png
|
|
:alt: event loop
|
|
|
|
The event loop does only necessary minimum and hand over message processing to
|
|
another thread. In fact, there can be as many processing threads as configured
|
|
increasing processing power.
|
|
|
|
To break this high level description into smaller pieces, here is what happens
|
|
when user calls an API:
|
|
|
|
#. User (or management application) calls a Libvirt API. Depending on the
|
|
connection URI, this may or may not involve server. Well, for the sake of our
|
|
demonstration we assume the former.
|
|
#. Remote driver encodes the API among it's arguments into an `RPC
|
|
message <rpc.html>`__ and sends it to the server.
|
|
#. Here, server is waiting in ``poll(2)`` for an event, like incoming message.
|
|
#. As soon as the first bytes of message are received, even loop wakes up and
|
|
server starts reading the whole message.
|
|
#. Once fully read, the event loop notifies threads known as worker threads from
|
|
which one picks the incoming message, decodes and process it.
|
|
#. As soon as API execution is finished, a reply is sent to the client.
|
|
|
|
In case that there's no free worker to process an incoming message in step 5,
|
|
message is placed at the end of a message queue and is processed in next
|
|
iteration.
|