[libvirt] [PATCH 13/16] docs: hacking: extend goto documentation
Replace reference to VIR_FREE with g_free and mention the use
of g_auto cleanup attributes that eliminate most of label use.
Signed-off-by: Ján Tomko <jtomko(a)redhat.com>
---
docs/hacking.html.in | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index 8c68cd1c3c..7f608657b3 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -1446,11 +1446,16 @@ BAD:
single label at the end of the function. It's almost always ok
to use this style. In particular, if the cleanup code only
involves free'ing memory, then having multiple labels is
- overkill. VIR_FREE() and every function named XXXFree() in
- libvirt is required to handle NULL as its arg. Thus you can
+ overkill. g_free() and most of the functions named XXXFree() in
+ libvirt is required to handle NULL as its arg. This does not
+ apply to libvirt's public APIs. Thus you can
safely call free on all the variables even if they were not yet
allocated (yes they have to have been initialized to NULL).
This is much simpler and clearer than having multiple labels.
+ Note that most of libvirt's type declarations can be marked with
+ either <code>g_autofree</code> or <code>g_autoptr</code>
which uses
+ the compiler's <code>__attribute__((cleanup))</code> that calls
+ the appropriate free function when the variable goes out of scope.
</p>
<p>
--
2.21.0