[libvirt] [PATCH 08/16] docs: hacking: mention GLib alternatives of libvirt allocation macros

[Daniel P. Berrangé]

On Sat, Oct 19, 2019 at 12:36:42AM +0200, Ján Tomko wrote:
> 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 at 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>

s/g_new/g_new0/

> +        <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>

g_renew is fine here again.

> +        <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>

We should probably suggest people to use 'g_autofree' in the variable
declaration wherever practical. 

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|