OpenE2K/qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

docs/style: call out the use of GUARD macros

Browse Source 
There use makes our code safer so we should mention them.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Reviewed-by: Juan Quintela <quintela@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
Message-Id: <20230424092249.58552-19-alex.bennee@linaro.org>
This commit is contained in:
Alex Bennée 2023-04-24 10:22:49 +01:00
parent 067109a11c
commit ef46ae67ba
1 changed files with 54 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
docs/devel/style.rst
View File

@ -665,6 +665,60 @@ Note that there is no need to provide typedefs for QOM structures
since these are generated automatically by the QOM declaration macros.
See :ref:`qom` for more details.
QEMU GUARD macros
=================
QEMU provides a number of ``_GUARD`` macros intended to make the
handling of multiple exit paths easier. For example using
``QEMU_LOCK_GUARD`` to take a lock will ensure the lock is released on
exit from the function.
.. code-block:: c
static int my_critical_function(SomeState *s, void *data)
{
QEMU_LOCK_GUARD(&s->lock);
do_thing1(data);
if (check_state2(data)) {
return -1;
}
do_thing3(data);
return 0;
}
will ensure s->lock is released however the function is exited. The
equivalent code without _GUARD macro makes us to carefully put
qemu_mutex_unlock() on all exit points:
.. code-block:: c
static int my_critical_function(SomeState *s, void *data)
{
qemu_mutex_lock(&s->lock);
do_thing1(data);
if (check_state2(data)) {
qemu_mutex_unlock(&s->lock);
return -1;
}
do_thing3(data);
qemu_mutex_unlock(&s->lock);
return 0;
}
There are often ``WITH_`` forms of macros which more easily wrap
around a block inside a function.
.. code-block:: c
WITH_RCU_READ_LOCK_GUARD() {
QTAILQ_FOREACH_RCU(kid, &bus->children, sibling) {
err = do_the_thing(kid->child);
if (err < 0) {
return err;
}
}
}
Error handling and reporting
============================