libvirt/docs/glib-adoption.rst

Adoption of GLib APIs

Libvirt has adopted use of the GLib library. 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:

VIR_ALLOC, VIR_REALLOC, VIR_RESIZE_N, VIR_EXPAND_N, VIR_SHRINK_N, VIR_FREE, VIR_APPEND_ELEMENT, VIR_INSERT_ELEMENT, VIR_DELETE_ELEMENT

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.

virStrerror

The GLib g_strerror() function should be used instead, which has a simpler calling convention as an added benefit.

The following libvirt APIs have been deleted already:

VIR_AUTOPTR, VIR_AUTOCLEAN, VIR_AUTOFREE

The GLib macros g_autoptr, g_auto and g_autofree must be used instead in all new code. In existing code, the GLib macros must never be mixed with libvirt macros within a method, nor should they be mixed with VIR_FREE. If introducing GLib macros to an existing method, any use of libvirt macros must be converted in an independent commit.

VIR_DEFINE_AUTOPTR_FUNC, VIR_DEFINE_AUTOCLEAN_FUNC

The GLib macros G_DEFINE_AUTOPTR_CLEANUP_FUNC and G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC must be used in all new code. Existing code should be converted to the new macros where relevant. It is permissible to use g_autoptr, g_auto on an object whose cleanup function is declared with the libvirt macros and vice-versa.

VIR_AUTOUNREF

The GLib macros g_autoptr and G_DEFINE_AUTOPTR_CLEANUP_FUNC should be used to manage autoclean of virObject classes. This matches usage with GObject classes.

VIR_STRDUP, VIR_STRNDUP

Prefer the GLib APIs g_strdup and g_strndup.

deleted version	GLib version	Notes
VIR_AUTOPTR	g_autoptr
VIR_AUTOCLEAN	g_auto
VIR_AUTOFREE	g_autofree	The GLib version does not use parentheses
VIR_AUTOUNREF	g_autoptr	The cleanup function needs to be defined
VIR_DEFINE_AUTOPTR_FUNC	G_DEFINE_AUTOPTR_CLEANUP_FUNC
VIR_DEFINE_AUTOCLEAN_FUNC	G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC
VIR_STEAL_PTR	g_steal_pointer	a = f(&b) instead of f(a, b)
VIR_RETURN_PTR	return g_steal_pointer
ARRAY_CARDINALITY	G_N_ELEMENTS
ATTRIBUTE_FALLTHROUGH	G_GNUC_FALLTHROUGH
ATTRIBUTE_FMT_PRINTF	G_GNUC_PRINTF
ATTRIBUTE_NOINLINE	G_GNUC_NO_INLINE
ATTRIBUTE_NORETURN	G_GNUC_NORETURN
ATTRIBUTE_RETURN_CHECK	G_GNUC_WARN_UNUSED_RESULT
ATTRIBUTE_SENTINEL	G_GNUC_NULL_TERMINATED
ATTRIBUTE_UNUSED	G_GNUC_UNUSED
VIR_STRDUP	g_strdup
VIR_STRNDUP	g_strndup
virStrerror	g_strerror