7:28 a.m.
Ján Tomko (6):
Revert "docs: Drop glib-adoption.rst"
docs: build glib-adoption.html
docs: glib-adoption: remove stuff we alredy removed
docs: glib-adoption: split into sections
docs: glib-adoption: add links to GLib documentation
docs: glib-adoption: add string arrays and objects
docs/glib-adoption.rst | 54 ++++++++++++++++++++++++++++++++++++++++++
docs/hacking.rst | 1 +
docs/meson.build | 1 +
3 files changed, 56 insertions(+)
create mode 100644 docs/glib-adoption.rst
--
2.26.2
7:28 a.m.
New subject: [libvirt PATCH 1/6] Revert "docs: Drop glib-adoption.rst"
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 @@
+=====================
+Adoption of GLib APIs
+=====================
+
+Libvirt has adopted use of the `GLib
+library <https://developer.gnome.org/glib/stable/>`__. 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`` |
|
++-------------------------------+--------------------------------------+-------------------------------------------+
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 <programming-languages.html>`__
- `Developer tooling <developer-tooling.html>`__
- `Advanced test suite usage <advanced-tests.html>`__
+- `Adoption of GLib APIs <glib-adoption.html>`__
- `Committer guidelines <committer-guidelines.html>`__
--
2.26.2
7:28 a.m.
New subject: [libvirt PATCH 2/6] docs: build glib-adoption.html
We switched to meson in the meantime so the conversion
to HTML has to be explicitly requested.
Signed-off-by: Ján Tomko <jtomko(a)redhat.com>
---
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 = [
'formatbackup',
'formatcheckpoint',
'formatdomain',
+ 'glib-adoption',
'hacking',
'kbase',
'libvirt-go',
--
2.26.2
7:28 a.m.
New subject: [libvirt PATCH 3/6] docs: glib-adoption: remove stuff we alredy removed
https://www.redhat.com/archives/libvir-list/2020-May/msg00299.html
Suggested-by: Daniel P. Berrangé <berrange(a)redhat.com>
Signed-off-by: Ján Tomko <jtomko(a)redhat.com>
---
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 | 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`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
--
2.26.2
7:28 a.m.
New subject: [libvirt PATCH 4/6] docs: glib-adoption: split into sections
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án Tomko <jtomko(a)redhat.com>
---
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:
-``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.
--
2.26.2
9:46 a.m.
New subject: [libvirt PATCH 4/6] docs: glib-adoption: split into sections
On Thu, 2020-09-24 at 14:28 +0200, Ján Tomko wrote:
+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.
Part of this hunk is the result not of actual changes in the
contents, but rather of switching to two-spaces-between-sentences
style, which is incidentally not the style used in the rest of the
file. So, please don't do that :)
--
Andrea Bolognani / Red Hat / Virtualization
7:28 a.m.
New subject: [libvirt PATCH 5/6] docs: glib-adoption: add links to GLib documentation
Make life a bit easier for people unfamiliar with GLib.
Signed-off-by: Ján Tomko <jtomko(a)redhat.com>
---
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``
+ 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``
+ 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
--
2.26.2
7:28 a.m.
New subject: [libvirt PATCH 6/6] docs: glib-adoption: add string arrays and objects
Signed-off-by: Ján Tomko <jtomko(a)redhat.com>
---
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.html
+
+ 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.
--
2.26.2
9:47 a.m.
On Thu, 2020-09-24 at 14:28 +0200, Ján Tomko wrote:
Ján Tomko (6):
Revert "docs: Drop glib-adoption.rst"
docs: build glib-adoption.html
docs: glib-adoption: remove stuff we alredy removed
docs: glib-adoption: split into sections
docs: glib-adoption: add links to GLib documentation
docs: glib-adoption: add string arrays and objects
docs/glib-adoption.rst | 54 ++++++++++++++++++++++++++++++++++++++++++
docs/hacking.rst | 1 +
docs/meson.build | 1 +
3 files changed, 56 insertions(+)
create mode 100644 docs/glib-adoption.rst
With the comment in 4/6 addressed,
Reviewed-by: Andrea Bolognani <abologna(a)redhat.com>
--
Andrea Bolognani / Red Hat / Virtualization
1513
days inactive
1520
days old
8 comments
2 participants
participants (2)
-
Andrea Bolognani -
Ján Tomko