diff options
author | Alex Bennée <alex.bennee@linaro.org> | 2023-04-24 10:22:49 +0100 |
---|---|---|
committer | Alex Bennée <alex.bennee@linaro.org> | 2023-04-27 14:58:51 +0100 |
commit | ef46ae67ba9a785cf0cce58b5fc5a36ed3c6c7b9 (patch) | |
tree | beec35b1dcd68057c21fce9401d66421e0004521 /docs/devel/style.rst | |
parent | 067109a11c83e0b461d7a1a9b531b4c738323477 (diff) | |
download | qemu-ef46ae67ba9a785cf0cce58b5fc5a36ed3c6c7b9.zip qemu-ef46ae67ba9a785cf0cce58b5fc5a36ed3c6c7b9.tar.gz qemu-ef46ae67ba9a785cf0cce58b5fc5a36ed3c6c7b9.tar.bz2 |
docs/style: call out the use of GUARD macros
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>
Diffstat (limited to 'docs/devel/style.rst')
-rw-r--r-- | docs/devel/style.rst | 54 |
1 files changed, 54 insertions, 0 deletions
diff --git a/docs/devel/style.rst b/docs/devel/style.rst index ac2ce42..aa5e083 100644 --- a/docs/devel/style.rst +++ b/docs/devel/style.rst @@ -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 ============================ |