libvirt/docs/internals/eventloop.html.in
Andrea Bolognani 630f376bc0 docs: Move all images to a subdirectory
This unclutters the top-level docs directory.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Ani Sinha <ani@anisinha.ca>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-01-04 15:47:25 +01:00

107 lines
4.2 KiB
XML

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<body>
<h1>Libvirt's event loop</h1>
<ul id="toc"></ul>
<p>
This page describes the event loop approach used in
libvirt. Both server and client.
</p>
<h2><a id="event_loop">Event driven programming</a></h2>
<p>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.</p>
<p>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.</p>
<img alt="event loop" src="../images/event_loop_simple.png"/>
<p>In Libvirt this approach is used in combination with
<code>poll(2)</code> 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. </p>
<h2><a id="api">The event loop API</a></h2>
<p>To work with event loop from our code we have plenty of
APIs.</p>
<ul>
<li><code>virEventAddHandle</code>: Registers a
callback for monitoring file handle events.</li>
<li><code>virEventUpdateHandle</code>: Change set of events
monitored file handle is being watched for.</li>
<li><code>virEventRemoveHandle</code>: Unregisters
previously registered file handle so that it is no
longer monitored for any events.</li>
<li><code>virEventAddTimeout</code>: Registers a
callback for timer event.</li>
<li><code>virEventUpdateTimeout</code>: Changes frequency
for a timer.</li>
<li><code>virEventRemoveTimeout</code>: Unregisters
a timer.</li>
</ul>
<p>For more information on these APIs continue reading <a
href="../html/libvirt-libvirt-event.html">here</a>.</p>
<h2><a id="worker_pool">Worker pool</a></h2>
<p>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.</p>
<img alt="event loop" src="../images/event_loop_worker.png"/>
<p>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.</p>
<p>To break this high level description into smaller pieces,
here is what happens when user calls an API:</p>
<ol>
<li>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.</li>
<li>Remote driver encodes the API among it's arguments
into an <a href="rpc.html">RPC message</a> and sends
it to the server.</li>
<li>Here, server is waiting in <code>poll(2)</code> for
an event, like incoming message.</li>
<li>As soon as the first bytes of message are received,
even loop wakes up and server starts reading the
whole message.</li>
<li>Once fully read, the event loop notifies threads
known as worker threads from which one picks the incoming
message, decodes and process it.</li>
<li>As soon as API execution is finished, a reply is sent
to the client.</li>
</ol>
<p>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.</p>
</body>
</html>