From nobody Sun Feb 8 15:46:14 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1571235970; cv=none; d=zoho.com; s=zohoarc; b=VFIEG/BMv+qnp3wkkNMyvr5yFpb4RJUBOQIPZwrcruslQNbzY4D85V1h/+eEi7A4Y4JYkJXjaMCK6lf1ER0wtxr6LHn6oLmCQovyCZGiOaQXQ4yqMRIhC859YfQX4hNqK6M0ixamYtT7Y64kkUYyCbV+M+RAWoL/8xF5KcB9hmk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1571235970; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=K0F5xkdi5SeHCQta2Q4K4RPQqdrD+YKUhRK4iRmicDU=; b=g4WKM0z+MoFTVMZPVAlxKtv4EOct1rF0U7z1zySRM2jRPDL+iDV51ANi/EbG4SvDVkUPzH73zyhel0YxSyz1A8drAn/PxFTeY/n3UFWXtlnQx+BQntyiiE/ljloeZ3teUODNwfb6ha8d+u3OotLOnH78g1TTo0+WIyHM7B7BECw= ARC-Authentication-Results: i=1; mx.zoho.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1571235970924745.5092539972711; Wed, 16 Oct 2019 07:26:10 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 301272CE95A; Wed, 16 Oct 2019 14:26:09 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id E436260C80; Wed, 16 Oct 2019 14:26:08 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 824FC1803B48; Wed, 16 Oct 2019 14:26:08 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id x9GENsEh028013 for ; Wed, 16 Oct 2019 10:23:54 -0400 Received: by smtp.corp.redhat.com (Postfix) id 516DB4C99; Wed, 16 Oct 2019 14:23:54 +0000 (UTC) Received: from lpt.redhat.com (ovpn-200-52.brq.redhat.com [10.40.200.52]) by smtp.corp.redhat.com (Postfix) with ESMTP id ABC154C98 for ; Wed, 16 Oct 2019 14:23:53 +0000 (UTC) From: =?UTF-8?q?J=C3=A1n=20Tomko?= To: libvir-list@redhat.com Date: Wed, 16 Oct 2019 16:24:41 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH 2/3] docs: hacking: use for functions/names X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.29]); Wed, 16 Oct 2019 14:26:09 +0000 (UTC) Use the element more in the GLib section. Signed-off-by: J=C3=A1n Tomko --- docs/hacking.html.in | 47 ++++++++++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 21 deletions(-) diff --git a/docs/hacking.html.in b/docs/hacking.html.in index 92826c5d44..ecf52ffc17 100644 --- a/docs/hacking.html.in +++ b/docs/hacking.html.in @@ -1008,28 +1008,32 @@ BAD:

=20
-
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.
=20 -
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.
=20 -
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_vpri= nt should be used + instead. Don't use g_vasprintf unless having the stri= ng length returned is unavoidable.
=20 -
virStrerror
+
virStrerror
The GLib g_strerror() function should be used inste= ad, 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 macr= os to an existing method, any use of libvirt macros must be converted in an independent commit.
=20 -
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 cle= anup function is declared with the libvirt macros and vice-verca.
=20 -
VIR_AUTOUNREF
-
The GLib macros g_autoptr and G_DEFINE_AUTOPTR_CLEANUP_FUNC +
VIR_AUTOUNREF
+
The GLib macros g_autoptr and G_DEFINE_AUTOPT= R_CLEANUP_FUNC should be used to manage autoclean of virObject classes. This matches usage with GObject classes.
--=20 2.21.0 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list