[libvirt] [PATCH 08/16] 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(a)redhat.com>
---
docs/hacking.html.in | 21 +++++++++++++++++++++
1 file changed, 21 insertions(+)
diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index ad0f595897..f39f6433d4 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -1050,6 +1050,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_new(var_t,
1)</code></td>
+ <td>yes, you need to tell it the type 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>no
alternative</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>
--
2.21.0