From: Ján Tomko Date: Wed, 16 Oct 2019 12:43:49 +0000 (+0200) Subject: docs: hacking: use for functions/names X-Git-Tag: v5.9.0-rc1~176 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=6a73c8f2c191181884e40f6456a25e40095d0329;p=thirdparty%2Flibvirt.git docs: hacking: use for functions/names Use the element more in the GLib section. Signed-off-by: Ján Tomko Reviewed-by: Michal Privoznik --- diff --git a/docs/hacking.html.in b/docs/hacking.html.in index 92826c5d44..6bae7f5f64 100644 --- a/docs/hacking.html.in +++ b/docs/hacking.html.in @@ -1008,28 +1008,32 @@ BAD:

-
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. +
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 + 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.
-
VIR_STRDUP, VIR_STRNDUP
-
Prefer the GLib APIs g_strdup and g_strndup.
+
VIR_STRDUP, VIR_STRNDUP
+
Prefer the GLib APIs g_strdup and g_strndup.
-
virAsprintf, virVasprintf
-
The GLib APIs g_strdup_printf / g_strdup_vprint should be used - instead. Don't use g_vasprintf unless having the string length +
virAsprintf, virVasprintf
+
The GLib APIs g_strdup_printf / g_strdup_vprint should be used + instead. Don't use g_vasprintf unless having the string length returned is unavoidable.
-
virStrerror
+
virStrerror
The GLib g_strerror() function should be used instead, which has a simpler calling convention as an added benefit.
@@ -1038,26 +1042,27 @@ BAD: 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 +
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 + 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 +
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 + g_autoptr, g_auto on an object whose cleanup function is declared with the libvirt macros and vice-verca.
-
VIR_AUTOUNREF
-
The GLib macros g_autoptr and G_DEFINE_AUTOPTR_CLEANUP_FUNC +
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.