[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[RFC PATCH] docs/devel: expand style section of memory management
From: |
Alex Bennée |
Subject: |
[RFC PATCH] docs/devel: expand style section of memory management |
Date: |
Mon, 15 Mar 2021 16:53:12 +0000 |
This aims to provide a bit more guidance for those who take on one of
our "clean up memory allocation" bite-sized tasks.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
docs/devel/style.rst | 40 ++++++++++++++++++++++++++++++----------
1 file changed, 30 insertions(+), 10 deletions(-)
diff --git a/docs/devel/style.rst b/docs/devel/style.rst
index 8b0bdb3570..823fa6f209 100644
--- a/docs/devel/style.rst
+++ b/docs/devel/style.rst
@@ -385,17 +385,35 @@ avoided.
Low level memory management
===========================
-Use of the malloc/free/realloc/calloc/valloc/memalign/posix_memalign
+Use of the ``malloc/free/realloc/calloc/valloc/memalign/posix_memalign``
APIs is not allowed in the QEMU codebase. Instead of these routines,
-use the GLib memory allocation routines g_malloc/g_malloc0/g_new/
-g_new0/g_realloc/g_free or QEMU's qemu_memalign/qemu_blockalign/qemu_vfree
-APIs.
+use the GLib memory allocation routines
+``g_malloc/g_malloc0/g_new/g_new0/g_realloc/g_free``
+or QEMU's ``qemu_memalign/qemu_blockalign/qemu_vfree`` APIs.
-Please note that g_malloc will exit on allocation failure, so there
-is no need to test for failure (as you would have to with malloc).
-Calling g_malloc with a zero size is valid and will return NULL.
+Please note that ``g_malloc`` will exit on allocation failure, so there
+is no need to test for failure (as you would have to with ``malloc``).
-Prefer g_new(T, n) instead of g_malloc(sizeof(T) ``*`` n) for the following
+Care should be taken to avoid introducing places where the guest could
+trigger an exit. For example using ``g_malloc`` on start-up is fine
+if the result of a failure is going to be a fatal exit anyway. There
+may be some start-up cases where failing is unreasonable (for example
+speculatively loading debug symbols).
+
+However if we are doing an allocation because of something the guest
+has done we should never trigger an exit. The code may deal with this
+by trying to allocate less memory and continue or re-designed to allocate
+buffers on start-up.
+
+If the lifetime of the allocation is within the function and there are
+multiple exist paths you can also improve the readability of the code
+by using ``g_autofree`` and related annotations. See :ref:`autofree-ref`
+for more details.
+
+
+Calling ``g_malloc`` with a zero size is valid and will return NULL.
+
+Prefer ``g_new(T, n)`` instead of ``g_malloc(sizeof(T) * n)`` for the following
reasons:
* It catches multiplication overflowing size_t;
@@ -409,8 +427,8 @@ Declarations like
are acceptable, though.
-Memory allocated by qemu_memalign or qemu_blockalign must be freed with
-qemu_vfree, since breaking this will cause problems on Win32.
+Memory allocated by ``qemu_memalign`` or ``qemu_blockalign`` must be freed with
+``qemu_vfree``, since breaking this will cause problems on Win32.
String manipulation
===================
@@ -485,6 +503,8 @@ In addition, QEMU assumes that the compiler does not use
the latitude
given in C99 and C11 to treat aspects of signed '<<' as undefined, as
documented in the GNU Compiler Collection manual starting at version 4.0.
+.. _autofree-ref:
+
Automatic memory deallocation
=============================
--
2.20.1
- [RFC PATCH] docs/devel: expand style section of memory management,
Alex Bennée <=