Re: [PATCH V4 03/24] libxl.h: document the paradigm of using libxl types

[Ian Campbell <Ian.Campbell@citrix.com>]

On Tue, 2014-05-06 at 14:12 +0100, Ian Jackson wrote:
> Ian Campbell writes ("Re: [PATCH V4 03/24] libxl.h: document the paradigm of using libxl types"):
> > On Thu, 2014-05-01 at 13:58 +0100, Wei Liu wrote:
> > > Signed-off-by: Wei Liu <wei.liu2@citrix.com>
> > 
> > I think this reflects reality even if it's not what we would actually
> > have wanted.
> 
> If we intend to change it, we should say so.
> 
> > > + * The paradigm of using libxl types is that user always calls "init"
> > > + * function before using a type, and always calls "dispose" after using
> > > + * a type to clean up, regardless of the operations on this type
> > > + * succeed or fail. See xl code for examples.
> 
> Here's a version which reads slightly better to a native speaker and
> is IMO slightly less ambiguous:
> 
>   * 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.
> 
> I would add:
> 
>   * "init" is idempotent.  We intend that "dispose" will become
>   * idempotent, but this is not currently the case.

I suppose this last bit corresponds to "if we intend to change it" so
should be included iff that is the case.

I can see that it would be desirable to make that change, but I'm not
sure how any application could ever make use of it, since older versions
will crash horribly, and if they were to use a #ifdef
LIBXL_HAVE_IDEMPOTENT_DISPOSE, well, then they could just have called it
once.

I suppose if they only care about Xen >= the version with the change
they could make use of it.

Ian.