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

[Eric Blake]

On Sun, Aug 20, 2023 at 02:16:24PM +, 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 *)
>  | SectionLink of string(** link to L *)
> -- 
> 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 

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org
___
Libguestfs mailing list
Libguestfs@redhat.com
https://listman.redhat.com/mailman/listinfo/libguestfs

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

[Tage Johansson]

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
[`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(+)

diff --git a/generator/API.ml b/generator/API.ml
index 72c8165..99fcb82 100644
--- a/generator/API.ml
+++ b/generator/API.ml
@@ -32,6 +32,7 @@ type call = {
   permitted_states : permitted_state list;
   is_locked : bool;
   may_set_error : bool;
+  async_kind : async_kind option;
   mutable first_version : int * int;
 }
 and arg =
@@ -102,6 +103,9 @@ and permitted_state =
 | Negotiating
 | Connected
 | Closed | Dead
+and async_kind =
+| WithCompletionCallback
+| ChangesState of string * bool
 and link =
 | Link of string
 | SectionLink of string
@@ -250,6 +254,7 @@ let default_call = { args = []; optargs = []; ret = RErr;
  see_also = [];
  permitted_states = [];
  is_locked = true; may_set_error = true;
+ async_kind = None;
  first_version = (0, 0) }
 
 (* Calls.
@@ -2802,6 +2807,7 @@ wait for an L.";
 default_call with
 args = [ SockAddrAndLen ("addr", "addrlen") ]; ret = RErr;
 permitted_states = [ Created ];
+async_kind = Some (ChangesState ("aio_is_connecting", false));
 shortdesc = "connect to the NBD server";
 longdesc = "\
 Begin connecting to the NBD server.  The C and C
@@ -2814,6 +2820,7 @@ parameters specify the address of the socket to connect 
to.
 default_call with
 args = [ String "uri" ]; ret = RErr;
 permitted_states = [ Created ];
+async_kind = Some (ChangesState ("aio_is_connecting", false));
 shortdesc = "connect to an NBD URI";
 longdesc = "\
 Begin connecting to the NBD URI C.  Parameters behave as
@@ -2827,6 +2834,7 @@ documented in L.
 default_call with
 args = [ Path "unixsocket" ]; ret = RErr;
 permitted_states = [ Created ];
+async_kind = Some (ChangesState ("aio_is_connecting", false));
 shortdesc = "connect to the NBD server over a Unix domain socket";
 longdesc = "\
 Begin connecting to the NBD server over Unix domain socket
@@ -2841,6 +2849,7 @@ L.
 default_call with
 args = [ UInt32 "cid"; UInt32 "port" ]; ret = RErr;
 permitted_states = [ Created ];
+async_kind = Some (ChangesState ("aio_is_connecting", false));
 shortdesc = "connect to the NBD server over AF_VSOCK socket";
 longdesc = "\
 Begin connecting to the NBD server over the C
@@ -2854,6 +2863,7 @@ L.
 default_call with
 args = [ String "hostname"; String "port" ]; ret = RErr;
 permitted_states = [ Created ];
+async_kind = Some (ChangesState ("aio_is_connecting", false));
 shortdesc = "connect to the NBD server over a TCP port";
 longdesc = "\
 Begin connecting to the NBD server listening on C.
@@ -2866,6 +2876,7 @@ Parameters behave as documented in L.
 default_call with
 args = [ Fd "sock" ]; ret = RErr;
 permitted_states = [ Created ];
+async_kind = Some (ChangesState ("aio_is_connecting", false));
 shortdesc = "connect directly to a connected socket";
 longdesc = "\
 Begin connecting to the connected socket C.
@@ -2878,6 +2889,7 @@ Parameters behave as documented in 
L.
 default_call with
 args = [ StringList "argv" ]; ret = RErr;
 permitted_states = [ Created ];
+async_kind = Some (ChangesState ("aio_is_connecting", false));
 shortdesc = "connect to the NBD server";
 longdesc = "\
 Run the command as a subprocess and begin connecting to it over
@@ -2891,6 +2903,7 @@ L.
 default_call with
 args = [ StringList "argv" ]; ret = RErr;
 permitted_states = [ Created ];
+async_kind = Some (ChangesState ("aio_is_connecting", false));
 shortdesc = "connect using systemd socket activation";
 longdesc = "\
 Run the command as a subprocess and begin connecting to it using
@@ -2907,6 +2920,7 @@ L.
 optargs = [ OClosure completion_closure ];
 ret = RErr;
 permitted_states = [ Negotiating ];
+async_kind = Some WithCompletionCallback;
 shortdesc = "end negotiation and move on to using an export";
 longdesc = "\
 Request that the server finish negotiation and move on to serving the
@@ -2930,6 +2944,7 @@ when L returns true.";
 default_call with
 args = []; ret = RErr;
 permitted_states = [ Negotiating ];
+async_kind = Some (ChangesState ("aio_is_connecting", false));
 shortdesc = "end negotiation and close the connection";
 longdesc = "\