mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-07-06 18:05:45 +00:00
c1f3a628d0
Signed-off-by: Ján Tomko <jtomko@redhat.com> Reviewed-by: Andrea Bolognani <abologna@redhat.com>
55 lines
2.0 KiB
ReStructuredText
55 lines
2.0 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``
|
|
|
|
https://developer.gnome.org/glib/stable/glib-Memory-Allocation.html
|
|
|
|
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``
|
|
|
|
https://developer.gnome.org/glib/stable/glib-Arrays.html
|
|
|
|
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.
|
|
|
|
String arrays
|
|
``virStringList*``, ``virStringListCount*``
|
|
|
|
https://developer.gnome.org/glib/stable/glib-String-Utility-Functions.html
|
|
|
|
Prefer the NULL-terminated variant instead of storing the count
|
|
separately. Prefer ``g_str*v`` functions instead of their ``vir*``
|
|
counterparts. For use with ``g_auto`` GLib provides the ``GStrv`` type.
|
|
|
|
Objects
|
|
``virObject``
|
|
|
|
https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html
|
|
|
|
Prefer ``GObject`` instead.
|