On 24.04.23 12:07, Alex Bennée wrote:
Vladimir Sementsov-Ogievskiy <vsement...@yandex-team.ru> writes:
On 20.04.23 18:57, Alex Bennée wrote:
There use makes our code safer so we should mention them.
Signed-off-by: Alex Bennée <alex.ben...@linaro.org>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsement...@yandex-team.ru>
---
docs/devel/style.rst | 36 ++++++++++++++++++++++++++++++++++++
1 file changed, 36 insertions(+)
diff --git a/docs/devel/style.rst b/docs/devel/style.rst
index 0bd01f3fca..b50a981a86 100644
--- a/docs/devel/style.rst
+++ b/docs/devel/style.rst
@@ -657,6 +657,42 @@ that declaration and the new code.
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;
+ }
For more clearness, maybe add an equivalent code with qemu_mutex_lock() /
qemu_mutex_unlock(), I mean:
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;
}
+
+will ensure s->lock is released however the function is exited. 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;
+ }
+ }
+ }
+
and maybe similar here.
I added the example although I didn't repeat it for the WITH form
because readers should hopefully have understood the idea with the first
example.
Agreed, thanks!
--
Best regards,
Vladimir