Re: [Xen-devel] [PATCH 22/24] libxl: clarify definition of "slow" operation

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Mon, 2012-04-16 at 18:18 +0100, Ian Jackson wrote:
> 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>

> ---
>  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).



_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel