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

[Wei Liu <wei.liu2@xxxxxxxxxx>]

On Tue, May 06, 2014 at 02:12:20PM +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@xxxxxxxxxx>
> > 
> > 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 will use your version. Thanks.

Wei.

> Ian.

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