From: Ján Tomko <jtomko@redhat.com>
Date: Fri, 18 Oct 2019 21:12:19 +0000 (+0200)
Subject: docs: hacking: mention GLib alternatives of libvirt allocation macros
X-Git-Tag: v5.9.0-rc1~73
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=48f48b27afe97284d2ba8208663320c8f0554421;p=thirdparty%2Flibvirt.git

docs: hacking: mention GLib alternatives of libvirt allocation macros

Document the preferred alternatives to existing libvirt macros for
memory allocation. These cannot be deleted just yet because
converting them will require a lot of work.

Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
---

diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index f3ad43eee7..0f4587522d 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -1051,6 +1051,27 @@ BAD:
       <dt><code>virStrerror</code></dt>
       <dd>The GLib <code>g_strerror()</code> function should be used instead,
         which has a simpler calling convention as an added benefit.</dd>
+
+    <table class="top_table">
+        <tr><th>deprecated version</th><th>GLib version</th><th>Notes</th></tr>
+        <tr><td><code>VIR_ALLOC(var)</code></td><td><code>g_new0(var_t, 1)</code></td>
+            <td>the type needs to be passed explicitly</td></tr>
+        <tr><td><code>VIR_ALLOC_N</code></td><td><code>g_new0(var_t, n)</code></td><td></td></tr>
+        <tr><td><code>VIR_REALLOC_N</code></td><td><code>g_renew(var_t, ptr, n)</code></td>
+            <td>the newly added memory is not zeroed</td></tr>
+        <tr><td><code>VIR_EXPAND_N</code></td><td><code>g_renew(var_t, ptr, n)</code></td>
+            <td>zero the new memory manually or use an array type</td></tr>
+        <tr><td><code>VIR_SHRINK_N</code></td><td>g_renew(var_t, ptr, n)</td>
+            <td></td></tr>
+        <tr><td><code>VIR_APPEND_ELEMENT</code></td><td><code>g_array_append_val</code></td>
+            <td><code>g_ptr_array_add</code> or <code>g_byte_array_append</code></td></tr>
+        <tr><td><code>VIR_INSERT_ELEMENT</code></td><td><code>g_array_insert_val</code></td>
+            <td><code>g_ptr_array_insert</code></td></tr>
+        <tr><td><code>VIR_DELETE_ELEMENT</code></td><td><code>g_array_remove_index</code></td>
+            <td><code>g_ptr_array_remove_index</code> or <code>g_byte_array_remove_index</code></td></tr>
+        <tr><td><code>VIR_FREE</code></td><td><code>g_free</code></td>
+            <td><code>g_free</code> does not zero the pointer</td></tr>
+    </table>
     </dl>
 
     <p>