From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ian Jackson Subject: [PATCH 22/24] libxl: clarify definition of "slow" operation Date: Mon, 16 Apr 2012 18:18:04 +0100 Message-ID: <1334596686-8479-23-git-send-email-ian.jackson@eu.citrix.com> References: <1334596686-8479-1-git-send-email-ian.jackson@eu.citrix.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <1334596686-8479-1-git-send-email-ian.jackson@eu.citrix.com> List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xen.org Errors-To: xen-devel-bounces@lists.xen.org To: xen-devel@lists.xen.org Cc: Ian Jackson List-Id: xen-devel@lists.xenproject.org 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 Signed-off-by: Ian Jackson --- 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 b77a891..fb4dee8 100644 --- a/tools/libxl/libxl_internal.h +++ b/tools/libxl/libxl_internal.h @@ -1399,17 +1399,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