Re: [libvirt] [PATCH v2 06/23] util: rewrite auto cleanup macros to use glib's equivalent

To facilitate porting over to glib, this rewrites the auto cleanup macros to use glib's equivalent. As a result it is now possible to use g_autoptr/VIR_AUTOPTR, and g_auto/VIR_AUTOCLEAN, g_autofree/VIR_AUTOFREE interchangably, regardless of which macros were used to declare the cleanup types. Within the scope of any single method, code must remain consistent using either GLib or Libvirt macros, never mixing both. New code must preferentially use the GLib macros, and old code will be converted incrementally. Signed-off-by: Daniel P. Berrangé <berrange(a)redhat.com&gt; --- cfg.mk | 2 +- docs/hacking.html.in | 18 ++++++++++++++++++ src/util/viralloc.h | 5 ++++- src/util/virautoclean.h | 38 ++++++++++++++++++++------------------ 4 files changed, 43 insertions(+), 20 deletions(-) diff --git a/cfg.mk b/cfg.mk index 3eae469165..7319a14d19 100644 --- a/cfg.mk +++ b/cfg.mk @@ -1061,7 +1061,7 @@ sc_prohibit_backslash_alignment: # Rule to ensure that variables declared using a cleanup macro are # always initialized. sc_require_attribute_cleanup_initialization: - @prohibit='VIR_AUTO((FREE|PTR|UNREF|CLEAN)\(.+\)|CLOSE|STRINGLIST) *[^=]+;' \ + @prohibit='((g_auto(ptr|free)?)|(VIR_AUTO((FREE|PTR|UNREF|CLEAN)\(.+\)|CLOSE|STRINGLIST))) *[^=]+;' \ in_vc_files='\.[chx]$$' \ halt='variable declared with a cleanup macro must be initialized' \ $(_sc_search_regexp) diff --git a/docs/hacking.html.in b/docs/hacking.html.in index 5839464e99..40a3c60573 100644 --- a/docs/hacking.html.in +++ b/docs/hacking.html.in @@ -1028,6 +1028,24 @@ BAD: <dd>The GLib APIs g_strdup_printf / g_strdup_vprint can be used, but beware that they don't abort on OOM, so the libvirt wrappers may still be desirable to use. Don't use g_vasprintf or g_asprintf.</dd> + + <dt>VIR_AUTOPTR, VIR_AUTOCLEAN, VIR_AUTOFREE</dt> + <dd>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. + </dd> + + <dt>VIR_DEFINE_AUTOPTR_FUNC, VIR_DEFINE_AUTOCLEAN_FUNC</dt> + <dd>The Gib 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 vica-verca.

+ </dd> </dl> <h2><a id="file_handling">File handling</a></h2> diff --git a/src/util/viralloc.h b/src/util/viralloc.h index 517f9aada6..f81ea42902 100644 --- a/src/util/viralloc.h +++ b/src/util/viralloc.h @@ -494,8 +494,11 @@ void virDisposeString(char **strptr) * VIR_AUTOFREE: * @type: type of the variable to be freed automatically * + * DEPRECATED: use g_autofree for new code. See hacking

+ * for further guidance. + * * Macro to automatically free the memory allocated to * the variable declared with it by calling virFree * when the variable goes out of scope. */ -#define VIR_AUTOFREE(type) __attribute__((cleanup(virFree))) type +#define VIR_AUTOFREE(type) g_autofree type diff --git a/src/util/virautoclean.h b/src/util/virautoclean.h index 6da288e67d..d7c1c1ec8b 100644 --- a/src/util/virautoclean.h +++ b/src/util/virautoclean.h @@ -20,7 +20,21 @@ #pragma once -#define VIR_AUTOPTR_FUNC_NAME(type) type##AutoPtrFree +/** + * DEPRECATION WARNING + * + * The macros in this file should not be used in newly written code. + * Use the equivalent GLib macros instead. + * + * For existing code, use of the libvirt and GLib macros must NEVER + * be mixed within a single method. + * + * The use of the libvirt VIR_FREE macros should also not be mixed + * with GLib auto-free macros and vica-verca.