[Xen-changelog] [xen-unstable] libxl: clarify definition of "slow" operation

[Xen patchbot-unstable <patchbot@xxxxxxx>]

# HG changeset patch
# User Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
# Date 1336759146 -3600
# Node ID 7de97a852161631d2ce387080fcf328956b6bccc
# Parent  1417d35592c0e47eaa7f619121bdb722b834cdde
libxl: clarify definition of "slow" operation

Update the comment in libxl_internal.h to be clearer about which
application-facing libxl operations need to take an ao_how.

Reported-by: Dan Magenheimer <dan.magenheimer@xxxxxxxxxx>
Signed-off-by: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
Acked-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
Committed-by: Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>
---


diff -r 1417d35592c0 -r 7de97a852161 tools/libxl/libxl_internal.h
--- a/tools/libxl/libxl_internal.h      Fri May 11 18:59:06 2012 +0100
+++ b/tools/libxl/libxl_internal.h      Fri May 11 18:59:06 2012 +0100
@@ -1439,17 +1439,34 @@ _hidden void libxl__egc_cleanup(libxl__e
 /*
  * Machinery for asynchronous operations ("ao")
  *
- * All "slow" functions (includes anything that might block on a
- * guest or an external script) need to use the asynchronous
- * operation ("ao") machinery.  The function should take a parameter
- * const libxl_asyncop_how *ao_how and must start with a call to
- * AO_INITIATOR_ENTRY.  These functions MAY NOT be called from
- * inside libxl, because they can cause reentrancy callbacks.
+ * All "slow" functions (see below for the exact definition) need to
+ * use the asynchronous operation ("ao") machinery.  The function
+ * should take a parameter const libxl_asyncop_how *ao_how and must
+ * start with a call to AO_INITIATOR_ENTRY.  These functions MAY NOT
+ * be called from inside libxl, because they can cause reentrancy
+ * callbacks.
  *
  * For the same reason functions taking an ao_how may make themselves
  * an egc with EGC_INIT (and they will generally want to, to be able
  * to immediately complete an ao during its setup).
  *
+ *
+ * "Slow" functions includes any that might block on a guest or an
+ * external script.  More broadly, it includes any operations which
+ * are sufficiently slow that an application might reasonably want to
+ * initiate them, and then carry on doing something else, while the
+ * operation completes.  That is, a "fast" function must be fast
+ * enough that we do not mind blocking all other management operations
+ * on the same host while it completes.
+ *
+ * There are certain primitive functions which make a libxl operation
+ * necessarily "slow" for API reasons.  These are:
+ *  - awaiting xenstore watches (although read-modify-write xenstore
+ *    transactions are OK for fast functions)
+ *  - spawning subprocesses
+ *  - anything with a timeout
+ *
+ *
  * Lifecycle of an ao:
  *
  * - Created by libxl__ao_create (or the AO_CREATE convenience macro).

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog