Re: [Xen-devel] [PATCH V5 07/32] libxl.h: document the paradigm of using libxl types

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Tue, 2014-05-13 at 22:53 +0100, Wei Liu wrote:
> Signed-off-by: Wei Liu <wei.liu2@xxxxxxxxxx>
> ---
>  tools/libxl/libxl.h |   10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/tools/libxl/libxl.h b/tools/libxl/libxl.h
> index 31877da..303bd71 100644
> --- a/tools/libxl/libxl.h
> +++ b/tools/libxl/libxl.h
> @@ -240,6 +240,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

calls should be just call here

> + * once afterwards, to clean up, regardless of whether operations on
> + * this object succeeded or failed.  See the xl code for examples.
> + *
> + * "init" is idempotent.

I wondered if this was true, or if calling it twice would leak. None of
the _init functions allocate any memory so this is OK, I think.

Calling init on a partially setup object could leak things though, so
init is only idempotent until you initialise some of the fields, which
isn't a terribly useful guarantee I don't think.

>   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



_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel