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

[Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>]

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.

Ian.

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