[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 18/18] docs/style: call out the use of GUARD macros
From: |
Alex Bennée |
Subject: |
[PULL 18/18] docs/style: call out the use of GUARD macros |
Date: |
Thu, 27 Apr 2023 16:45:10 +0100 |
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>
diff --git a/docs/devel/style.rst b/docs/devel/style.rst
index ac2ce42a2f..aa5e083ff8 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
============================
--
2.39.2
- [PULL 11/18] avocado_qemu/__init__.py: factor out the qemu-img finding, (continued)
- [PULL 11/18] avocado_qemu/__init__.py: factor out the qemu-img finding, Alex Bennée, 2023/04/27
- [PULL 10/18] MAINTAINERS: Cover tests/avocado/machine_aspeed.py, Alex Bennée, 2023/04/27
- [PULL 05/18] scripts/device-crash-test: Add a parameter to run with TCG only, Alex Bennée, 2023/04/27
- [PULL 08/18] tests/avocado: Make ssh_command_output_contains() globally available, Alex Bennée, 2023/04/27
- [PULL 12/18] tests/avocado/tuxrun_baselines.py: improve code coverage for ppc64, Alex Bennée, 2023/04/27
- [PULL 13/18] tests/tcg: limit the scope of the plugin tests, Alex Bennée, 2023/04/27
- [PULL 14/18] qemu-options.hx: Update descriptions of memory options for NUMA node, Alex Bennée, 2023/04/27
- [PULL 09/18] tests/avocado/machine_aspeed: Fix the broken ast2[56]00_evb_sdk tests, Alex Bennée, 2023/04/27
- [PULL 16/18] docs/devel: make a statement about includes, Alex Bennée, 2023/04/27
- [PULL 15/18] docs/system: remove excessive punctuation from guest-loader docs, Alex Bennée, 2023/04/27
- [PULL 18/18] docs/style: call out the use of GUARD macros,
Alex Bennée <=
- [PULL 17/18] docs/devel: mention the spacing requirement for QOM, Alex Bennée, 2023/04/27
- Re: [PULL 00/18] testing and doc updates, Richard Henderson, 2023/04/28