shaba/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2025-03-11 00:58:38 +03:00
Code Releases Activity

docs: Drop glib-adoption.rst

Browse Source 
It's been more than six months since we adopted GLib and we've
been pretty aggressive at replacing our homegrown APIs with more
standard ones, so by now most of the symbols mentioned in this
document haven't been around for quite a long time already.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
This commit is contained in:
Andrea Bolognani 2020-05-07 19:28:30 +02:00
parent 495a2e2778
commit 842d3712ed
2 changed files with 0 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
docs/glib-adoption.rst
View File

@ -1,96 +0,0 @@
=====================
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`` | |
+-------------------------------+--------------------------------------+-------------------------------------------+

1
docs/hacking.rst
View File

@ -75,5 +75,4 @@ 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>`__