mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-08-06 17:03:49 +00:00
900e54ed2e
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@redhat.com> Reviewed-by: Andrea Bolognani <abologna@redhat.com>
35 lines
1.4 KiB
ReStructuredText
35 lines
1.4 KiB
ReStructuredText
=====================
|
|
Adoption of GLib APIs
|
|
=====================
|
|
|
|
Libvirt has adopted use of the `GLib
|
|
library <https://developer.gnome.org/glib/stable/>`__. Due to
|
|
libvirt's long history of development, there are many APIs in
|
|
libvirt, for which GLib provides an alternative solution. The
|
|
general rule to follow is that the standard GLib solution will be
|
|
preferred over historical libvirt APIs. Existing code will be
|
|
ported over to use GLib APIs over time, but new code should use
|
|
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:
|
|
|
|
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``. **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.
|