Re: [Xen-devel] [PATCH 29/28] libxl: ao internal API docs: Mention synchronous ao completion

[Wei Liu <wei.liu2@xxxxxxxxxx>]

On Wed, Apr 08, 2015 at 12:37:58PM +0100, Ian Jackson wrote:
> This doc comment about ao lifecycle failed to mention the option of
> completing the ao during the initiator function.  (Indeed, the most
> obvious reading would forbid it.)
> 
> Restructure the comment, describe this situation, and generally
> improve the wording.
> 
> Also, fix a grammar problem (missing word `a').
> 
> CC: Koushik Chakravarty <koushik.chakravarty@xxxxxxxxxx>
> Reported-by: Koushik Chakravarty <koushik.chakravarty@xxxxxxxxxx>
> Signed-off-by: Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>

Acked-by: Wei Liu <wei.liu2@xxxxxxxxxx>

> ---
>  tools/libxl/libxl_internal.h |   33 +++++++++++++++++++++++----------
>  1 file changed, 23 insertions(+), 10 deletions(-)
> 
> diff --git a/tools/libxl/libxl_internal.h b/tools/libxl/libxl_internal.h
> index 35e6643..49c6779 100644
> --- a/tools/libxl/libxl_internal.h
> +++ b/tools/libxl/libxl_internal.h
> @@ -1955,28 +1955,41 @@ _hidden void libxl__egc_cleanup(libxl__egc *egc);
>   *        must be copied into the per-operation structure using
>   *        libxl__ao_progress_gethow.
>   *
> - * - If initiation is successful, the initiating function needs
> - *   to run libxl__ao_inprogress right before unlocking and
> - *   returning, and return whatever it returns (AO_INPROGRESS macro).
> - *
>   * - If the initiation is unsuccessful, the initiating function must
>   *   call libxl__ao_abort before unlocking and returning whatever
>   *   error code is appropriate (AO_ABORT macro).
>   *
> + * If initiation is successful:
> + *
> + * - The initiating function must run libxl__ao_inprogress right
> + *   before unlocking and returning, and return whatever it returns.
> + *   This is best achieved with the AO_INPROGRESS macro.
> + *
>   * - If the operation supports progress reports, it may generate
>   *   suitable events with NEW_EVENT and report them with
>   *   libxl__ao_progress_report (with the ctx locked).
>   *
> - * - Later, some callback function, whose callback has been requested
> - *   directly or indirectly, should call libxl__ao_complete (with the
> - *   ctx locked, as it will generally already be in any event callback
> - *   function).  This must happen exactly once for each ao (and not if
> - *   the ao has been destroyed, obviously).
> + * - Eventually, some callback function, whose callback has been
> + *   requested directly or indirectly, should call libxl__ao_complete
> + *   (with the ctx locked, as it will generally already be in any
> + *   event callback function).  This must happen exactly once for each
> + *   ao, as the last that happens with that ao.
> + *
> + * - However, it is permissible for the initiating function to call
> + *   libxl__ao_inprogress and/or libxl__ao_complete (directly or
> + *   indirectly), before it uses AO_INPROGRESS to return.  (The ao
> + *   infrastructure will arrange to defer destruction of the ao, etc.,
> + *   until the proper time.)  An initiating function should do this
> + *   if it takes a codepath which completes synchronously.
> + *
> + * - Conversely it is forbidden to call libxl__ao_complete in the
> + *   initiating function _after_ AO_INPROGRESS, because
> + *   libxl__ao_complete requires the ctx to be locked.
>   *
>   * - Note that during callback functions, two gcs are available:
>   *    - The one in egc, whose lifetime is only this callback
>   *    - The one in ao, whose lifetime is the asynchronous operation
> - *   Usually callback function should use CONTAINER_OF to obtain its
> + *   Usually a callback function should use CONTAINER_OF to obtain its
>   *   own state structure, containing a pointer to the ao.  It should
>   *   then obtain the ao and use the ao's gc; this is most easily done
>   *   using the convenience macro STATE_AO_GC.
> -- 
> 1.7.10.4

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