[Libguestfs] [libnbd PATCH v8 05/10] generator: Add information about asynchronous handle calls

[Eric Blake]

On Sun, Aug 20, 2023 at 02:16:24PM +0000, Tage Johansson wrote:
> A new field (async_kind) is added to the call data type in
> generator/API.ml*. The purpose is to tell if a certain handle call is
> an asynchronous command and if so how one can know when it is
> completed. The motivation for this is that all asynchronous commands
> on the AsyncHandle in the Rust bindings makes use of Rust's

s/makes/make/

> [`async fn`s](https://doc.rust-lang.org/std/keyword.async.html).
> But to implement such an async fn, the API needs to know when the
> command completed, either by a completion callback or via a change
> of state.
> ---
>  generator/API.ml  | 32 ++++++++++++++++++++++++++++++++
>  generator/API.mli | 11 +++++++++++
>  2 files changed, 43 insertions(+)
> 

> +++ b/generator/API.mli
> @@ -36,6 +36,11 @@ type call = {
>        {b guaranteed} never to do that we can save a bit of time by
>        setting this to false. *)
>    may_set_error : bool;
> +  (** There are two types of asynchronous functions, those with a completion
> +      callback and those which changes state when completed. This field tells

s/changes/change/

> +      if the function is asynchronous and in that case how one can check if
> +      it has completed. *)
> +  async_kind : async_kind option;
>    (** The first stable version that the symbol appeared in, for
>        example (1, 2) if the symbol was added in development cycle
>        1.1.x and thus the first stable version was 1.2.  This is
> @@ -117,6 +122,12 @@ and permitted_state =
>                                 not including CLOSED or DEAD *)
>  | Closed | Dead            (** can be called when the handle is
>                                 CLOSED or DEAD *)
> +and async_kind =
> +(** The asynchronous call has a completion callback. *)
> +| WithCompletionCallback
> +(** The asynchronous call is completed when the given handle call returns the
> +    given boolean value. Might for instance be ("aio_is_connected", false). *)
> +| ChangesState of string * bool
>  and link =
>  | Link of string           (** link to L<nbd_PAGE(3)> *)
>  | SectionLink of string    (** link to L<libnbd(3)/SECTION> *)
> -- 
> 2.41.0

Grammar changes can be made while merging; no need to respin unless
later patches require more substantive updates.

Reviewed-by: Eric Blake <eblake at redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org