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

[Eric Blake]

On 9/11/20 9:31 AM, Eric Blake wrote:
> 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.

An alternative to a new enum type is noting that the NBD protocol only 
has 16 bits for NBD_CMD_FLAG, but we have a uint32_t for our flags 
parameter.  We could declare that LIBNBD_CMD_FLAG_EXT_SHUTDOWN_IMMEDIATE 
has value 0x10000 (or however we name things to draw a distinction 
between flags passed over the wire vs. flags consumed only by libnbd), 
where the new extension flag is valid for nbd_shutdown but has no effect 
over the wire, and that would still leave the door open to pass through 
any actual 16-bit flag that the protocol ever adds for NBD_CMD_DISC.

> +++ 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 = "\


-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org