ian.jackson at eu
Apr 25, 2012, 8:55 AM
Post #1 of 1
Update the comment in libxl_internal.h to be clearer about which
[PATCH 23/25] libxl: clarify definition of "slow" operation
application-facing libxl operations need to take an ao_how.
Reported-by: Dan Magenheimer <dan.magenheimer [at] oracle>
Signed-off-by: Ian Jackson <ian.jackson [at] eu>
Acked-by: Ian Campbell <ian.campbell [at] citrix>
tools/libxl/libxl_internal.h | 29 +++++++++++++++++++++++------
1 files changed, 23 insertions(+), 6 deletions(-)
diff --git a/tools/libxl/libxl_internal.h b/tools/libxl/libxl_internal.h
index 55d07c4..459c27b 100644
@@ -1430,17 +1430,34 @@ _hidden void libxl__egc_cleanup(libxl__egc *egc);
* 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-devel mailing list
Xen-devel [at] lists