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

[Eric Blake]

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.
+
 The returned size must be E<ge> 0.  If there is an error, C<.get_size>
 should call C<nbdkit_error> with an error message and return C<-1>.

-- 
2.20.1