[Libguestfs] [nbdkit PATCH 4/4] doc: More details on (lack of) dynamic sizing

[Richard W.M. Jones]

On Sat, Apr 27, 2019 at 04:26:46PM -0500, Eric Blake wrote:
> We already documented in the lifetime section that .get_size is in the
> same boat as .can_write and friends, where the values reported may
> change between connections, but should generally remain constant for a
> given connection and that other parts of the code may cache rather
> than constantly re-check the callback.  However, it is worth a bit
> more detail directly on the .get_size callback, in particular
> mentioning that a server that allows externally growing images is
> generally safe.
> 
> When the NBD protocol extension for dynamic resize is finally
> implemented, we'll probably have to add more rules on how and when
> size can change.
> 
> Signed-off-by: Eric Blake <eblake at redhat.com>
> ---
>  docs/nbdkit-plugin.pod | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 
> diff --git a/docs/nbdkit-plugin.pod b/docs/nbdkit-plugin.pod
> index e9dc34f..15d571f 100644
> --- a/docs/nbdkit-plugin.pod
> +++ b/docs/nbdkit-plugin.pod
> @@ -479,6 +479,15 @@ check for errors, but obviously this is outside the scope of nbdkit.
>  This is called during the option negotiation phase of the protocol
>  to get the size (in bytes) of the block device being exported.
> 
> +The NBD protocol does not currently provide a way for a client to
> +learn about or request any dynamic size changes. Thus, although this
> +callback may return different values across different C<.open> calls,
> +other code in nbdkit may cache the size reported during open, rather
> +than checking for the current size. It is generally safe to report a
> +larger size than before (even if the client will not access beyond the
> +original size), but risky to shrink an image below the size in use by
> +any current connection.

I'm in two minds about documenting things that (a) might change in
future and (b) seem a bit dangerous -- is it really safe to report
larger sizes?

So personally I'd either leave this undocumented, or if you want to
write something then say that at the moment the plugin should always
return the same size, but future changes to the NBD protocol might
implement resizing with the cooperation of the plugin.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
Fedora Windows cross-compiler. Compile Windows programs, test, and
build Windows installers. Over 100 libraries supported.
http://fedoraproject.org/wiki/MinGW