Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Xen: Devel

[PATCH 23/25] libxl: clarify definition of "slow" operation

 

 

Xen devel RSS feed   Index | Next | Previous | View Threaded


ian.jackson at eu

Apr 25, 2012, 8:55 AM

Post #1 of 1 (58 views)
Permalink
[PATCH 23/25] 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 [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
--- a/tools/libxl/libxl_internal.h
+++ b/tools/libxl/libxl_internal.h
@@ -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).
--
1.7.2.5


_______________________________________________
Xen-devel mailing list
Xen-devel [at] lists
http://lists.xen.org/xen-devel

Xen devel RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.