[Libguestfs] [libnbd PATCH v9 1/7] generator: Add information about asynchronous handle calls

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 make 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<eventfd(2)>."; 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<addr> and C<addrlen> @@ -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<uri>. Parameters behave as @@ -2827,6 +2834,7 @@ documented in L<nbd_connect_uri(3)>. 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<nbd_connect_unix(3)>. 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<AF_VSOCK> @@ -2854,6 +2863,7 @@ L<nbd_connect_vsock(3)>. 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<hostname:port>. @@ -2866,6 +2876,7 @@ Parameters behave as documented in L<nbd_connect_tcp(3)>. 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<fd>. @@ -2878,6 +2889,7 @@ Parameters behave as documented in L<nbd_connect_socket(3)>. 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<nbd_connect_command(3)>. 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<nbd_connect_systemd_socket_activation(3)>. 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<nbd_aio_is_negotiating(3)> 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 = "\ Request that the server finish negotiation, gracefully if possible, then @@ -2947,6 +2962,7 @@ L<nbd_aio_is_connecting(3)> to return false."; optargs = [ OClosure completion_closure ]; ret = RErr; permitted_states = [ Negotiating ]; + async_kind = Some WithCompletionCallback; shortdesc = "request the server to initiate TLS"; longdesc = "\ Request that the server initiate a secure TLS connection, by @@ -2971,6 +2987,7 @@ callback."; optargs = [ OClosure completion_closure ]; ret = RErr; permitted_states = [ Negotiating ]; + async_kind = Some WithCompletionCallback; shortdesc = "request the server to enable structured replies"; longdesc = "\ Request that the server use structured replies, by sending @@ -2995,6 +3012,7 @@ callback."; optargs = [ OClosure completion_closure ]; ret = RErr; permitted_states = [ Negotiating ]; + async_kind = Some WithCompletionCallback; shortdesc = "request the server to list all exports during negotiation"; longdesc = "\ Request that the server list all exports that it supports. This can @@ -3017,6 +3035,7 @@ callback."; optargs = [ OClosure completion_closure ]; ret = RErr; permitted_states = [ Negotiating ]; + async_kind = Some WithCompletionCallback; shortdesc = "request the server for information about an export"; longdesc = "\ Request that the server supply information about the export name @@ -3040,6 +3059,7 @@ callback."; args = [ Closure context_closure ]; ret = RInt; optargs = [ OClosure completion_closure ]; permitted_states = [ Negotiating ]; + async_kind = Some WithCompletionCallback; shortdesc = "request list of available meta contexts, using implicit query"; longdesc = "\ Request that the server list available meta contexts associated with @@ -3067,6 +3087,7 @@ callback."; args = [ StringList "queries"; Closure context_closure ]; ret = RInt; optargs = [ OClosure completion_closure ]; permitted_states = [ Negotiating ]; + async_kind = Some WithCompletionCallback; shortdesc = "request list of available meta contexts, using explicit query"; longdesc = "\ Request that the server list available meta contexts associated with @@ -3094,6 +3115,7 @@ callback."; args = [ Closure context_closure ]; ret = RInt; optargs = [ OClosure completion_closure ]; permitted_states = [ Negotiating ]; + async_kind = Some WithCompletionCallback; shortdesc = "select specific meta contexts, with implicit query list"; longdesc = "\ Request that the server supply all recognized meta contexts @@ -3127,6 +3149,7 @@ callback."; args = [ StringList "queries"; Closure context_closure ]; ret = RInt; optargs = [ OClosure completion_closure ]; permitted_states = [ Negotiating ]; + async_kind = Some WithCompletionCallback; shortdesc = "select specific meta contexts, with explicit query list"; longdesc = "\ Request that the server supply all recognized meta contexts @@ -3161,6 +3184,7 @@ callback."; OFlags ("flags", cmd_flags, Some []) ]; ret = RCookie; permitted_states = [ Connected ]; + async_kind = Some WithCompletionCallback; shortdesc = "read from the NBD server"; longdesc = "\ Issue a read command to the NBD server. @@ -3195,6 +3219,7 @@ Other parameters behave as documented in L<nbd_pread(3)>." OFlags ("flags", cmd_flags, Some ["DF"]) ]; ret = RCookie; permitted_states = [ Connected ]; + async_kind = Some WithCompletionCallback; shortdesc = "read from the NBD server"; longdesc = "\ Issue a read command to the NBD server. @@ -3227,6 +3252,7 @@ Other parameters behave as documented in L<nbd_pread_structured(3)>." OFlags ("flags", cmd_flags, Some ["FUA"; "PAYLOAD_LEN"]) ]; ret = RCookie; permitted_states = [ Connected ]; + async_kind = Some WithCompletionCallback; shortdesc = "write to the NBD server"; longdesc = "\ Issue a write command to the NBD server. @@ -3246,6 +3272,7 @@ completed. Other parameters behave as documented in L<nbd_pwrite(3)>." default_call with args = []; optargs = [ OFlags ("flags", cmd_flags, Some []) ]; ret = RErr; permitted_states = [ Connected ]; + async_kind = Some (ChangesState ("aio_is_closed", true)); shortdesc = "disconnect from the NBD server"; longdesc = "\ Issue the disconnect command to the NBD server. This is @@ -3273,6 +3300,7 @@ however, L<nbd_shutdown(3)> will call this function if appropriate."; OFlags ("flags", cmd_flags, Some []) ]; ret = RCookie; permitted_states = [ Connected ]; + async_kind = Some WithCompletionCallback; shortdesc = "send flush command to the NBD server"; longdesc = "\ Issue the flush command to the NBD server. @@ -3294,6 +3322,7 @@ Other parameters behave as documented in L<nbd_flush(3)>." OFlags ("flags", cmd_flags, Some ["FUA"]) ]; ret = RCookie; permitted_states = [ Connected ]; + async_kind = Some WithCompletionCallback; shortdesc = "send trim command to the NBD server"; longdesc = "\ Issue a trim command to the NBD server. @@ -3315,6 +3344,7 @@ Other parameters behave as documented in L<nbd_trim(3)>." OFlags ("flags", cmd_flags, Some []) ]; ret = RCookie; permitted_states = [ Connected ]; + async_kind = Some WithCompletionCallback; shortdesc = "send cache (prefetch) command to the NBD server"; longdesc = "\ Issue the cache (prefetch) command to the NBD server. @@ -3337,6 +3367,7 @@ Other parameters behave as documented in L<nbd_cache(3)>." Some ["FUA"; "NO_HOLE"; "FAST_ZERO"]) ]; ret = RCookie; permitted_states = [ Connected ]; + async_kind = Some WithCompletionCallback; shortdesc = "send write zeroes command to the NBD server"; longdesc = "\ Issue a write zeroes command to the NBD server. @@ -3359,6 +3390,7 @@ Other parameters behave as documented in L<nbd_zero(3)>." OFlags ("flags", cmd_flags, Some ["REQ_ONE"]) ]; ret = RCookie; permitted_states = [ Connected ]; + async_kind = Some WithCompletionCallback; shortdesc = "send block status command to the NBD server"; longdesc = "\ Send the block status command to the NBD server. diff --git a/generator/API.mli b/generator/API.mli index c5bba8c..6fc11a9 100644 --- a/generator/API.mli +++ 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 change state when completed. This field tells + 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.42.0