[Xen-changelog] [xen master] libxl.h: document the paradigm of using libxl types

[patchbot@xxxxxxx]

commit 00bfad10f82a0b5554a96e37aed7187c6f374112
Author:     Wei Liu <wei.liu2@xxxxxxxxxx>
AuthorDate: Tue May 13 22:53:49 2014 +0100
Commit:     Ian Campbell <ian.campbell@xxxxxxxxxx>
CommitDate: Wed May 21 10:59:53 2014 +0100

    libxl.h: document the paradigm of using libxl types
    
    Signed-off-by: Wei Liu <wei.liu2@xxxxxxxxxx>
    Acked-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
---
 tools/libxl/libxl.h |   10 ++++++++++
 1 files changed, 10 insertions(+), 0 deletions(-)

diff --git a/tools/libxl/libxl.h b/tools/libxl/libxl.h
index c7aa817..896ecab 100644
--- a/tools/libxl/libxl.h
+++ b/tools/libxl/libxl.h
@@ -245,6 +245,16 @@
  * libxl_types.idl). The library provides a common set of methods for
  * initialising and freeing these types.
  *
+ * IDL-generated libxl types should be used as follows: the user must
+ * always call the "init" function before using a type, even if the
+ * variable is simply being passed by reference as an out parameter
+ * to a libxl function.  The user must always calls "dispose" exactly
+ * once afterwards, to clean up, regardless of whether operations on
+ * this object succeeded or failed.  See the xl code for examples.
+ *
+ * "init" is idempotent.  We intend that "dispose" will become
+ * idempotent, but this is not currently the case.
+ *
  * void libxl_<type>_init(<type> *p):
  *
  *    Initialises the members of "p" to all defaults. These may either
--
generated by git-patchbot for /home/xen/git/xen.git#master

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog