From nobody Fri May 3 15:07:51 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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=1600950561; cv=none; d=zohomail.com; s=zohoarc; b=n8omjURFi4AHDoDeQ9RJssuzKnDdYxMk93zEAAbJGxcI18gC92ZAnRe+e9cZr13mtoTMAY5MWPy5iuQJvKEZrCZWftiHttr+qESlU6H70axD46RxbLJnzHX3fDxNLb32zcmxVO8r3QzIBXDsboNATsQ0VHPjF+NLV29WxRIpZj4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1600950561; 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=ZK0VuKjj6Z/vrJbt6HFwpC8pQ3Y4ftj89+WF3XDPE1o=; b=gt2XHVz1w2KWBNyV4xBKWZonjRL1AIZZZju0D0GPm8wyoCpQeO1S3udldgRz+LjhSPaA5rO4uvW/UGo/Xr1Wbn3lwBkWK7Lalt1D549mqy1acZNlV7aIv2ViJ89vmB1ZihaeoZ0KZtYVTRkN7as/o3nVIPUfLnY1CsS7b+bzFL0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1600950561404933.7703575824447; Thu, 24 Sep 2020 05:29:21 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-595-HWQ5vNOPNsujXAP9s9l3fg-1; Thu, 24 Sep 2020 08:29:18 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id B6F761091062; Thu, 24 Sep 2020 12:29:11 +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 58B3373672; Thu, 24 Sep 2020 12:29:11 +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 24B4C181A050; Thu, 24 Sep 2020 12:29:09 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 08OCSlcd016086 for ; Thu, 24 Sep 2020 08:28:47 -0400 Received: by smtp.corp.redhat.com (Postfix) id 6AEE173684; Thu, 24 Sep 2020 12:28:47 +0000 (UTC) Received: from lpt.redhat.com (unknown [10.40.208.52]) by smtp.corp.redhat.com (Postfix) with ESMTP id D313773682 for ; Thu, 24 Sep 2020 12:28:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1600950560; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=ZK0VuKjj6Z/vrJbt6HFwpC8pQ3Y4ftj89+WF3XDPE1o=; b=ebrwNWi1jxo1bCN+IcaJWhhjZUDdMz3A4wJB/0Kq7zPD76mUt8NAXpCjN+91HD1xsaEKx+ 3RhX8EtDkR9IhB+BE5utbzZqm7xx3rmpArBf6YttIOrrQEJFp4sy/b/uSHJwjnTqXMTHlA lWQfuZifI+rlHR0hwSx5VCBYSPaOSLc= X-MC-Unique: HWQ5vNOPNsujXAP9s9l3fg-1 From: =?UTF-8?q?J=C3=A1n=20Tomko?= To: libvir-list@redhat.com Subject: [libvirt PATCH 1/6] Revert "docs: Drop glib-adoption.rst" Date: Thu, 24 Sep 2020 14:28:35 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-loop: libvir-list@redhat.com 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: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Cleaning up after Andrea as he requested: https://www.redhat.com/archives/libvir-list/2020-May/msg00405.html This reverts commit 842d3712ed612f213b454e610cc7ff9db2321803 --- docs/glib-adoption.rst | 96 ++++++++++++++++++++++++++++++++++++++++++ docs/hacking.rst | 1 + 2 files changed, 97 insertions(+) create mode 100644 docs/glib-adoption.rst diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst new file mode 100644 index 0000000000..62ddd7c61d --- /dev/null +++ b/docs/glib-adoption.rst @@ -0,0 +1,96 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Adoption of GLib APIs +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 | N= otes | ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ +| ``VIR_AUTOPTR`` | ``g_autoptr`` | = | ++-------------------------------+--------------------------------------+--= -----------------------------------------+ +| ``VIR_AUTOCLEAN`` | ``g_auto`` | = | ++-------------------------------+--------------------------------------+--= -----------------------------------------+ +| ``VIR_AUTOFREE`` | ``g_autofree`` | T= he GLib version does not use parentheses | ++-------------------------------+--------------------------------------+--= -----------------------------------------+ +| ``VIR_AUTOUNREF`` | ``g_autoptr`` | T= he 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 =3D 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`` | = | ++-------------------------------+--------------------------------------+--= -----------------------------------------+ diff --git a/docs/hacking.rst b/docs/hacking.rst index 858dd2dfc1..cd009c4c73 100644 --- a/docs/hacking.rst +++ b/docs/hacking.rst @@ -74,4 +74,5 @@ you also take a look at the following documents: - `Programming languages `__ - `Developer tooling `__ - `Advanced test suite usage `__ +- `Adoption of GLib APIs `__ - `Committer guidelines `__ --=20 2.26.2 From nobody Fri May 3 15:07:51 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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=1600950566; cv=none; d=zohomail.com; s=zohoarc; b=TYLftx3zSVodjouC1fgpPhCBEJP5N8dMH3kgjjNzuSzCvY56MeXQ6ZMG00fsy5AKrGAMS7jjZZ6yopDrl7+IOyXwcsTq1gJ8oIRKXtBqBU8PsYKOG65XYO+KLsAyHn2JBnqFjqYBT4579o9j1cGFqm3Kjft2EE8zzHzbKE0ehuM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1600950566; 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=85SWHXLripE4rd8ZLZRTBSqzYbsZurpkzjQkK3js1eY=; b=EU9du5pQ2xP7Fygfr6YCJjTjaiycLhGtvrpc2qGK8VTGynh8ML0m/ZMyM+tyCx+B6UZ5EoZ1yjzwpgtIE2a5zSD1NByRzCA/LIPAZQLg8s43NYHPxWoWa8PTe2lsdWnmeBUKYaV8O1R7vpcjhmYRslSsx6vNbuwxKY2XWQ0IRW8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1600950566501891.718317758365; Thu, 24 Sep 2020 05:29:26 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-583-FZd4sxZWMmCeLBWsyBw5fA-1; Thu, 24 Sep 2020 08:29:22 -0400 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 mimecast-mx01.redhat.com (Postfix) with ESMTPS id 752C86408E; Thu, 24 Sep 2020 12:29:17 +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 3B3C360CCC; Thu, 24 Sep 2020 12:29:17 +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 057A1181A06E; Thu, 24 Sep 2020 12:29:17 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 08OCSmoi016094 for ; Thu, 24 Sep 2020 08:28:48 -0400 Received: by smtp.corp.redhat.com (Postfix) id 6E58973684; Thu, 24 Sep 2020 12:28:48 +0000 (UTC) Received: from lpt.redhat.com (unknown [10.40.208.52]) by smtp.corp.redhat.com (Postfix) with ESMTP id DB30C73682 for ; Thu, 24 Sep 2020 12:28:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1600950565; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=85SWHXLripE4rd8ZLZRTBSqzYbsZurpkzjQkK3js1eY=; b=IweF3junGS5XtGpbAOMzxncx527dLwDtKd6ZQu2s7rlsm3VUCeo7Z5IFEjJhjBISPVIpil SGTgOAr2twCwM1hZSuryfNvfKT6kiAOLa6hG35atw6ZO/oWMOVBw9npPhaZ51yH2g056H0 LCirFMKIQpB5uvEZsz1fcx/OwNyqb5s= X-MC-Unique: FZd4sxZWMmCeLBWsyBw5fA-1 From: =?UTF-8?q?J=C3=A1n=20Tomko?= To: libvir-list@redhat.com Subject: [libvirt PATCH 2/6] docs: build glib-adoption.html Date: Thu, 24 Sep 2020 14:28:36 +0200 Message-Id: <2cbe19dd8c92e1cca685ac083ddfa459b2907b9b.1600950498.git.jtomko@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-loop: libvir-list@redhat.com 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: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) We switched to meson in the meantime so the conversion to HTML has to be explicitly requested. Signed-off-by: J=C3=A1n Tomko --- docs/meson.build | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/meson.build b/docs/meson.build index 7397d6409b..400c1ca955 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -117,6 +117,7 @@ docs_rst_files =3D [ 'formatbackup', 'formatcheckpoint', 'formatdomain', + 'glib-adoption', 'hacking', 'kbase', 'libvirt-go', --=20 2.26.2 From nobody Fri May 3 15:07:51 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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=1600950650; cv=none; d=zohomail.com; s=zohoarc; b=PpFylQ/989tO9daeEJD9+UXyNPo4skvlyXZ1pti99Tdx7GKzxQmWG88EFxzCvOq+TUQD0Iwjwc0ifS/JapEvxFwcROgeBmH0oDlUM79h/tx8PkF4yD9twuy25Ebdw/w0ci8tYqCkHOHB1FMudT6pzABP1WEtzcqiAAgCF4OfdOQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1600950650; 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=pmOyb2pn3FXg99iwCbjdc3glBUd3TFcLSOBKAfuZ5iI=; b=V7NkFTSBFAL64lhZcDUL7qWsAxOBQ6TcB3KjZUzXzMprXQvtoamOcYjy0KZ+x+i9Ih0nl/5EZXSnheST9pKzAiT3qBFsci0KmE3O78/DyecTexwjLJ3+jTRQWgZii+IYXEO/e8ESlkO5+HK553M1uNp2S3k/vzPXRVxzRAvVfyg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 1600950650453355.0742879533759; Thu, 24 Sep 2020 05:30:50 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-364-Y1uVMjA9N4iJeLB0fg6RAA-1; Thu, 24 Sep 2020 08:30:46 -0400 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 mimecast-mx01.redhat.com (Postfix) with ESMTPS id CB954802B4A; Thu, 24 Sep 2020 12:30:41 +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 9BBD660C15; Thu, 24 Sep 2020 12:30:41 +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 617A4181A06D; Thu, 24 Sep 2020 12:30:41 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 08OCSnM9016101 for ; Thu, 24 Sep 2020 08:28:49 -0400 Received: by smtp.corp.redhat.com (Postfix) id 5FB1273682; Thu, 24 Sep 2020 12:28:49 +0000 (UTC) Received: from lpt.redhat.com (unknown [10.40.208.52]) by smtp.corp.redhat.com (Postfix) with ESMTP id CECC47368F for ; Thu, 24 Sep 2020 12:28:48 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1600950649; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=pmOyb2pn3FXg99iwCbjdc3glBUd3TFcLSOBKAfuZ5iI=; b=JwNQO4y10Ftha4VQOdhVAkkorSbNvlq3ll2eYzUnon5bto8Y1RiFivScYCU1Uah3rp6RV7 dP4tP+Kv0OgkD5O3PceXqidvlqK11q6/BKVbbf8M4Fn9THBHSBTWTm98zZkK7Nha9Zv9Ln QDvCIMKbXECsr+AjVaMvp9rRaTEAlv0= X-MC-Unique: Y1uVMjA9N4iJeLB0fg6RAA-1 From: =?UTF-8?q?J=C3=A1n=20Tomko?= To: libvir-list@redhat.com Subject: [libvirt PATCH 3/6] docs: glib-adoption: remove stuff we alredy removed Date: Thu, 24 Sep 2020 14:28:37 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-loop: libvir-list@redhat.com 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: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) https://www.redhat.com/archives/libvir-list/2020-May/msg00299.html Suggested-by: Daniel P. Berrang=C3=A9 Signed-off-by: J=C3=A1n Tomko --- docs/glib-adoption.rst | 69 ------------------------------------------ 1 file changed, 69 deletions(-) diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst index 62ddd7c61d..91d0c66d91 100644 --- a/docs/glib-adoption.rst +++ b/docs/glib-adoption.rst @@ -25,72 +25,3 @@ used in new code, and their suggested GLib replacements: 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 | N= otes | -+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ -| ``VIR_AUTOPTR`` | ``g_autoptr`` | = | -+-------------------------------+--------------------------------------+--= -----------------------------------------+ -| ``VIR_AUTOCLEAN`` | ``g_auto`` | = | -+-------------------------------+--------------------------------------+--= -----------------------------------------+ -| ``VIR_AUTOFREE`` | ``g_autofree`` | T= he GLib version does not use parentheses | -+-------------------------------+--------------------------------------+--= -----------------------------------------+ -| ``VIR_AUTOUNREF`` | ``g_autoptr`` | T= he 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 =3D 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`` | = | -+-------------------------------+--------------------------------------+--= -----------------------------------------+ --=20 2.26.2 From nobody Fri May 3 15:07:51 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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=1600950724; cv=none; d=zohomail.com; s=zohoarc; b=DqsID5SZNTpdqyJ2DzS+l2y09DUpyXp7Pbftknl4CMOyD4lArU4/QRi2Vc3nfGzGbHdyTMwuKKTmM1bVXmRN4m8mZsF/6r12K/2V8FtWnYn/WEe07SY/7TauCSi6SYlK9msraePH9IkfTweRpRrKjRFLvk+e09a7wTiwVJ/HYc8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1600950724; 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=NofmaRw3jGmXcFceWkxseARbKxPZigFx4kwDpfLc/rs=; b=VVJpQcc9fuOyymJ7fOzAQ28XxPc/X/50y+zdTTub2k+s6UeIP2uNPO3sptRRnKaNstEUqMshp8/r06sYVzDSW9x2MX8CH8XYPFJ8LPX+zrxAxpCdAggQjGIEcevGJdYnnZm7L3ivRhhoTgS8XFYAL4E5Ce0bWOvcuXnZjlcfla0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1600950724242203.3671157657194; Thu, 24 Sep 2020 05:32:04 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-277-fE8HWDlKOD-8cQAETrrCcA-1; Thu, 24 Sep 2020 08:31:18 -0400 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 mimecast-mx01.redhat.com (Postfix) with ESMTPS id 8B7631017DD5; Thu, 24 Sep 2020 12:31:12 +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 5A6FC6716C; Thu, 24 Sep 2020 12:31:12 +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 1AD4F181A06D; Thu, 24 Sep 2020 12:31:12 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 08OCSo7E016111 for ; Thu, 24 Sep 2020 08:28:50 -0400 Received: by smtp.corp.redhat.com (Postfix) id 83CA973672; Thu, 24 Sep 2020 12:28:50 +0000 (UTC) Received: from lpt.redhat.com (unknown [10.40.208.52]) by smtp.corp.redhat.com (Postfix) with ESMTP id E741381C40 for ; Thu, 24 Sep 2020 12:28:49 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1600950722; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=NofmaRw3jGmXcFceWkxseARbKxPZigFx4kwDpfLc/rs=; b=PFy9quanxU6NHLLiEjHXmzU6SzYIscPjcnTlYus2FmgSvT7P0HE/ofeBLxTaz23XjHC17h wNxYFarF8hOAL2c24OU5JHtmIMei0Pf37iOTm4D0GAL4YKpeIz+kwEpwk3i4FTeglI5/Eu VhBaaUU6Zi86ExNrxGhVq0kJE4Q8oto= X-MC-Unique: fE8HWDlKOD-8cQAETrrCcA-1 From: =?UTF-8?q?J=C3=A1n=20Tomko?= To: libvir-list@redhat.com Subject: [libvirt PATCH 4/6] docs: glib-adoption: split into sections Date: Thu, 24 Sep 2020 14:28:38 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-loop: libvir-list@redhat.com 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: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Although all the mentioned functions deal with allocation, replacing the pure allocation functions is easier than converting code to use GArrays. Split them out to encourage usage of GLib allocation APIs even at the cost of them being combined with VIR_*ELEMENT APIs. Signed-off-by: J=C3=A1n Tomko --- docs/glib-adoption.rst | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst index 91d0c66d91..fc0a8cfb08 100644 --- a/docs/glib-adoption.rst +++ b/docs/glib-adoption.rst @@ -14,14 +14,21 @@ 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: =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`` +Memory allocation + ``VIR_ALLOC``, ``VIR_REALLOC``, ``VIR_RESIZE_N``, + ``VIR_EXPAND_N``, ``VIR_SHRINK_N``, ``VIR_FREE`` + 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. + 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`` + + 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. --=20 2.26.2 From nobody Fri May 3 15:07:51 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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=1600950657; cv=none; d=zohomail.com; s=zohoarc; b=EWTuTJC6tPjXNzFoBxj/YS2UzwoRI/Z/9zPMojWZ7ouwHx6CeNZrg/3x18JfPP4G3b6jJvSe5RIbrisy6sKU3B20GLP55TC30hv8WynCjs6FBEA7ESs5mMjWYof/JGbE4Y9uefCSLhvFQIm8vz1Tu+Oggi6HtCZznQqYFfsGrq4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1600950657; 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=65x8dld+XFV6x2W7ky/V1B14OX/RXwtqHpYXuUou1s8=; b=V5sscDI7eiP4N3Ehrv80Dz5N+C3PdGEkfafXO87Ii1Sexb9jA7yp2eOQyIpFEFbIY36l2kVGF2ijOlacTaNJhfjUMUgJuiEUv12CydTOoizr8Rff4eXusQ0C/cH0Hcl+pSCUAHZEETuWVgJF7w25ECiR6JCbQddUKqhYnTuIhwk= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1600950657489472.4093332713247; Thu, 24 Sep 2020 05:30:57 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-441-tcnSXW8gOyG0nLfm0OEKvA-1; Thu, 24 Sep 2020 08:30:53 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 815D181F03C; Thu, 24 Sep 2020 12:30:47 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 5F5CC5C1C7; Thu, 24 Sep 2020 12:30:47 +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 2550544A5E; Thu, 24 Sep 2020 12:30:47 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 08OCSpTv016123 for ; Thu, 24 Sep 2020 08:28:51 -0400 Received: by smtp.corp.redhat.com (Postfix) id 745EB73672; Thu, 24 Sep 2020 12:28:51 +0000 (UTC) Received: from lpt.redhat.com (unknown [10.40.208.52]) by smtp.corp.redhat.com (Postfix) with ESMTP id DCA947368C for ; Thu, 24 Sep 2020 12:28:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1600950656; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=65x8dld+XFV6x2W7ky/V1B14OX/RXwtqHpYXuUou1s8=; b=FGYOlneoiqVaEhBV/BDYps//pAzu/tIKCYI26X8nHwIRS7QGgT1rUc/1hBQ0sbZMaVVpiK Dq6sgu7J0uTBgOcyASWBYooFsZl8+St3wT1ODrj1ZTSnlA4E6ddxFEm+oUI/ylDPkTboB7 esTd05S4IlveAsP/akb2XrDQUpgjoS4= X-MC-Unique: tcnSXW8gOyG0nLfm0OEKvA-1 From: =?UTF-8?q?J=C3=A1n=20Tomko?= To: libvir-list@redhat.com Subject: [libvirt PATCH 5/6] docs: glib-adoption: add links to GLib documentation Date: Thu, 24 Sep 2020 14:28:39 +0200 Message-Id: <2ffcf1437d928eee844b10481746342a54c4616f.1600950498.git.jtomko@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-loop: libvir-list@redhat.com 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: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Make life a bit easier for people unfamiliar with GLib. Signed-off-by: J=C3=A1n Tomko --- docs/glib-adoption.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst index fc0a8cfb08..6dcd4bc14e 100644 --- a/docs/glib-adoption.rst +++ b/docs/glib-adoption.rst @@ -18,6 +18,8 @@ Memory allocation ``VIR_ALLOC``, ``VIR_REALLOC``, ``VIR_RESIZE_N``, ``VIR_EXPAND_N``, ``VIR_SHRINK_N``, ``VIR_FREE`` =20 + 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 @@ -28,6 +30,8 @@ Memory allocation Array operations ``VIR_APPEND_ELEMENT``, ``VIR_INSERT_ELEMENT``, ``VIR_DELETE_ELEMENT`` =20 + 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 --=20 2.26.2 From nobody Fri May 3 15:07:51 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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=1600950570; cv=none; d=zohomail.com; s=zohoarc; b=Z667+62E1TcTnYZHRg4WcrnOu1b37BJOiWWlY/gOg7xW4f4cZDRwN7Gx58vJTx1dhx6rjFWcNI6iyLSExz6EtImNFZMvdEK+SjeSii/sfBGZTfHREw3DEeDk2+9+RNmBW8jCiV1HHaUFkymisOyyRuzrJD32dTDo2/ddidPiHtI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1600950570; 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=ZW4D667j6d+vfITUDK9oUyC+qmIZyH+l3dhYDFCtSqA=; b=GC2+JHSyKqUCRO3RoiYyPhfwfLQWgdqtcRwAy7mgHStKZp+AJhVS1XhHUF5PaCpZR2rYjtIwYWfofMXxMMjDHsBTRtoVwLYhQjtTmIrq6fRxfvrwViFTNPr20zcnCKwouoTYz8FKb9vYSCC9TZ1aSQ4XGpWw7PCLF309BxkXSlU= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1600950570288938.5225644530191; Thu, 24 Sep 2020 05:29:30 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-7-Lfu50MFBNRWy51o194gpqQ-1; Thu, 24 Sep 2020 08:29:26 -0400 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 mimecast-mx01.redhat.com (Postfix) with ESMTPS id 842971891E83; Thu, 24 Sep 2020 12:29:20 +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 5F37760E1C; Thu, 24 Sep 2020 12:29:20 +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 29D92181A07D; Thu, 24 Sep 2020 12:29:20 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 08OCSqrq016132 for ; Thu, 24 Sep 2020 08:28:52 -0400 Received: by smtp.corp.redhat.com (Postfix) id 761AA73682; Thu, 24 Sep 2020 12:28:52 +0000 (UTC) Received: from lpt.redhat.com (unknown [10.40.208.52]) by smtp.corp.redhat.com (Postfix) with ESMTP id DD3D573672 for ; Thu, 24 Sep 2020 12:28:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1600950569; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=ZW4D667j6d+vfITUDK9oUyC+qmIZyH+l3dhYDFCtSqA=; b=AumTOq6JWyXtNqeok4ETPumuSIP63RKlI6/RVr/OcHTYaIUa5p+BgbpnN3UXjpI0m8raO4 eXyal2e8VTUlSF98dc5hanDSuFv3TYiwzrF04fH16BS9QBihjDQPf1fW0UeMpX1Yj4IwkX OZ/s+GMmey56CtbUf6jmFoZFueNAVJM= X-MC-Unique: Lfu50MFBNRWy51o194gpqQ-1 From: =?UTF-8?q?J=C3=A1n=20Tomko?= To: libvir-list@redhat.com Subject: [libvirt PATCH 6/6] docs: glib-adoption: add string arrays and objects Date: Thu, 24 Sep 2020 14:28:40 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-loop: libvir-list@redhat.com 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: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Signed-off-by: J=C3=A1n Tomko --- docs/glib-adoption.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst index 6dcd4bc14e..96bea98e87 100644 --- a/docs/glib-adoption.rst +++ b/docs/glib-adoption.rst @@ -36,3 +36,19 @@ Array operations 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.h= tml + + 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. --=20 2.26.2