Re: [Xen-devel] [PATCH 07/10] libxl: New API for providing OS events to libxl

[Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>]

Ian Campbell writes ("Re: [Xen-devel] [PATCH 07/10] libxl: New API for 
providing OS events to libxl"):
> I think it is worth stating explicitly. e.g. "You should never need to
> initialise an egc unless you are part of the event machinery itself,
> Otherwise you will always be given an egc if you need one". I might even
> go as far as s/should never/will never/.

Right, that's good wording, thanks.

> > How about:
> >   #define EGC_GC  libxl__gc *gc = &egc->gc
> > ?
> 
> Works for me.

I will do this.

> > The functions which make their own egc, and which are therefore
> > forbidden for other callers inside libxl, are things like
> >    libxl_osevent_beforepoll
> >    libxl_event_wait
> > and if you're calling those from within libxl you are definitely doing
> > the whole thing entirely wrong.
...
> Makes sense, I think the wording I proposed above describes this?

Right.

Ian.

diff --git a/tools/libxl/libxl_internal.h b/tools/libxl/libxl_internal.h
index e03a5d6..c50c058 100644
--- a/tools/libxl/libxl_internal.h
+++ b/tools/libxl/libxl_internal.h
@@ -967,10 +967,12 @@ libxl__device_model_version_running(libxl__gc *gc, 
uint32_t domid);
  * call libxl__event_occurred.  These contain a gc but also a list of
  * deferred events.
  *
- * Most code in libxl should not need to initialise their own egc.
- * Even functions which generate specific kinds of events don't need
- * to - rather, they will be passed an egc into their own callback
- * function and should just use the one they're given.
+ * You should never need to initialise an egc unless you are part of
+ * the event machinery itself.  Otherwise you will always be given an
+ * egc if you need one.  Even functions which generate specific kinds
+ * of events don't need to - rather, they will be passed an egc into
+ * their own callback function and should just use the one they're
+ * given.
  *
  * A handy idiom for functions taking an egc is:
  *     libxl__gc *gc = &egc->gc;
@@ -978,7 +980,9 @@ libxl__device_model_version_running(libxl__gc *gc, uint32_t 
domid);
  * Functions using LIBXL__INIT_EGC may *not* generally be called from
  * within libxl, because libxl__egc_cleanup may call back into the
  * application.  This should be documented near the function
- * prototype(s) for callers of LIBXL__INIT_EGC and EGC_INIT.
+ * prototype(s) for callers of LIBXL__INIT_EGC and EGC_INIT.  You
+ * should in any case not find it necessary to call egc-creators from
+ * within libxl.
  *
  * For the same reason libxl__egc_cleanup (or EGC_FREE) must be called
  * with the ctx *unlocked*.  So the right pattern has the EGC_...

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel