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(a)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