Re: [Libguestfs] [libnbd PATCH] api: Add LIBNBD_SHUTDOWN_IMMEDIATE flag

As mentioned in commits 176fc4ea and 609c25f0, our original plan in adding a flags argument to nbd_shutdown was to let us specify different behaviors at the libnbd level, rather than NBD protocol flags (for that, the user has nbd_aio_disconnect). But when we later parameterized OFlags to accept various bitmasks (commit f891340b), we failed to mark nbd_shutdown as using a different bitmask than NBD_CMD_FLAG. I've finally found a use for such a flag. By itself, nbd_aio_disconnect merely queues itself at the back of all pending commands. But if the server is processing responses slowly, it can be desirable to elevate a disconnect request to the front of the queue, intentionally abandoning all subsequent commands that have not already started on their way to the server. Fortunately, we have been rejecting all flag values, so changing the type of the OFlags argument now has no impact to either the C API or the ABI. Other language bindings that are more strongly-typed will see a different enum, but we don't promise compatibility there, and even then, languages that permit omitting the flags argument in favor of a default don't see any difference for client that were omitting the argument in favor of the default. Note that the new LIBNBD_SHUTDOWN_IMMEDIATE flag is not necessarily instant: if the server is still receiving the previous command, we have to wait for that before the server can learn of our intent, and the command itself still blocks until we enter closed or dead states. But it can certainly reduce the time spent in nbd_shutdown by not having to wait for all unsent commands in the queue to also be processed by the server.

+++ b/generator/API.ml

@@ -1595,7 +1602,7 @@ L<nbd_can_fua(3)>)."; "shutdown", { default_call with - args = []; optargs = [ OFlags ("flags", cmd_flags) ]; ret = RErr; + args = []; optargs = [ OFlags ("flags", shutdown_flags) ]; ret = RErr; permitted_states = [ Connected ]; shortdesc = "disconnect from the NBD server"; longdesc = "\