[libvirt PATCH 4/6] docs: glib-adoption: split into sections
Although all the mentioned functions deal with
allocation, replacing the pure allocation
functions is easier than converting code to
use GArrays.
Split them out to encourage usage of GLib
allocation APIs even at the cost of them
being combined with VIR_*ELEMENT APIs.
Signed-off-by: Ján Tomko <jtomko(a)redhat.com>
---
docs/glib-adoption.rst | 27 +++++++++++++++++----------
1 file changed, 17 insertions(+), 10 deletions(-)
diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst
index 91d0c66d91..fc0a8cfb08 100644
--- a/docs/glib-adoption.rst
+++ b/docs/glib-adoption.rst
@@ -14,14 +14,21 @@ the GLib APIs straight away where possible.
The following is a list of libvirt APIs that should no longer be
used in new code, and their suggested GLib replacements:
-``VIR_ALLOC``, ``VIR_REALLOC``, ``VIR_RESIZE_N``, ``VIR_EXPAND_N``, ``VIR_SHRINK_N``,
``VIR_FREE``, ``VIR_APPEND_ELEMENT``, ``VIR_INSERT_ELEMENT``, ``VIR_DELETE_ELEMENT``
+Memory allocation
+ ``VIR_ALLOC``, ``VIR_REALLOC``, ``VIR_RESIZE_N``,
+ ``VIR_EXPAND_N``, ``VIR_SHRINK_N``, ``VIR_FREE``
+
Prefer the GLib APIs ``g_new0``/``g_renew``/ ``g_free`` in most
- cases. There should rarely be a need to use
- ``g_malloc``/``g_realloc``. Instead of using plain C arrays, it
- is preferrable to use one of the GLib types, ``GArray``,
- ``GPtrArray`` or ``GByteArray``. These all use a struct to
- track the array memory and size together and efficiently
- resize. **NEVER MIX** use of the classic libvirt memory
- allocation APIs and GLib APIs within a single method. Keep the
- style consistent, converting existing code to GLib style in a
- separate, prior commit.
+ cases. There should rarely be a need to use
+ ``g_malloc``/``g_realloc``. **NEVER MIX** use of the classic
+ libvirt memory allocation APIs and GLib APIs within a single
+ method. Keep the style consistent, converting existing code to
+ GLib style in a separate, prior commit.
+
+Array operations
+ ``VIR_APPEND_ELEMENT``, ``VIR_INSERT_ELEMENT``, ``VIR_DELETE_ELEMENT``
+
+ Instead of using plain C arrays, it is preferrable to use one of
+ the GLib types, ``GArray``, ``GPtrArray`` or ``GByteArray``.
+ These all use a struct to track the array memory and size
+ together and efficiently resize.
--
2.26.2