b4d42fa29b
Add nbdkit-cow-filter cow-on-read option. Add nbdkit-cache-filter cache-on-read=/PATH. Add nbdkit-cache-filter cache-min-block-size option. Add nbdkit-delay-filter delay-open and delay-close options. Reduce verbosity of debugging from virt-v2v. Miscellaneous bugfixes resolves: rhbz#1950632
105 lines
4.4 KiB
Diff
105 lines
4.4 KiB
Diff
From b6e1d14a052caf65dcc7e8fec2bf0d079e1f8a38 Mon Sep 17 00:00:00 2001
|
|
From: "Richard W.M. Jones" <rjones@redhat.com>
|
|
Date: Tue, 27 Jul 2021 22:42:52 +0100
|
|
Subject: [PATCH] docs: Improve documentation of .can_cache and .cache methods
|
|
|
|
(cherry picked from commit 0a6be5ae01a6079767e1fabd70cca73fc8520b1d)
|
|
---
|
|
docs/nbdkit-plugin.pod | 71 +++++++++++++++++++++++++-----------------
|
|
1 file changed, 43 insertions(+), 28 deletions(-)
|
|
|
|
diff --git a/docs/nbdkit-plugin.pod b/docs/nbdkit-plugin.pod
|
|
index 7a1fae8c..5e085e12 100644
|
|
--- a/docs/nbdkit-plugin.pod
|
|
+++ b/docs/nbdkit-plugin.pod
|
|
@@ -1047,19 +1047,29 @@ This callback is not required. If omitted, then we return false.
|
|
int can_cache (void *handle);
|
|
|
|
This is called during the option negotiation phase to find out if the
|
|
-plugin supports a cache operation. The nature of the caching is
|
|
-unspecified (including whether there are limits on how much can be
|
|
-cached at once, and whether writes to a cached region have
|
|
-write-through or write-back semantics), but the command exists to let
|
|
-clients issue a hint to the server that they will be accessing that
|
|
-region of the export.
|
|
-
|
|
-If this returns C<NBDKIT_CACHE_NONE>, cache support is not advertised
|
|
-to the client; if this returns C<NBDKIT_CACHE_EMULATE>, caching is
|
|
-emulated by the server calling C<.pread> and ignoring the results; if
|
|
-this returns C<NBDKIT_CACHE_NATIVE>, then the C<.cache> callback will
|
|
-be used. If there is an error, C<.can_cache> should call
|
|
-C<nbdkit_error> with an error message and return C<-1>.
|
|
+plugin supports a cache or prefetch operation.
|
|
+
|
|
+This can return:
|
|
+
|
|
+=over 4
|
|
+
|
|
+=item C<NBDKIT_CACHE_NONE>
|
|
+
|
|
+Cache support is not advertised to the client.
|
|
+
|
|
+=item C<NBDKIT_CACHE_EMULATE>
|
|
+
|
|
+Caching is emulated by the server calling C<.pread> and discarding the
|
|
+result.
|
|
+
|
|
+=item C<NBDKIT_CACHE_NATIVE>
|
|
+
|
|
+The C<.cache> callback will be called.
|
|
+
|
|
+=back
|
|
+
|
|
+If there is an error, C<.can_cache> should call C<nbdkit_error> with
|
|
+an error message and return C<-1>.
|
|
|
|
This callback is not required. If omitted, then we return
|
|
C<NBDKIT_CACHE_NONE> if the C<.cache> callback is missing, or
|
|
@@ -1284,23 +1294,28 @@ called. C<errno> will be set to a suitable value.
|
|
|
|
During the data serving phase, this callback is used to give the
|
|
plugin a hint that the client intends to make further accesses to the
|
|
-given region of the export. The nature of caching is not specified
|
|
-further by the NBD specification (for example, a server may place
|
|
-limits on how much may be cached at once, and there is no way to
|
|
-control if writes to a cached area have write-through or write-back
|
|
-semantics). In fact, the cache command can always fail and still be
|
|
-compliant, and success might not guarantee a performance gain. If
|
|
-this callback is omitted, then the results of C<.can_cache> determine
|
|
-whether nbdkit will reject cache requests, treat them as instant
|
|
-success, or emulate caching by calling C<.pread> over the same region
|
|
-and ignoring the results.
|
|
+given region of the export.
|
|
+
|
|
+The nature of caching/prefetching is not specified further by the NBD
|
|
+specification. For example, a server may place limits on how much may
|
|
+be cached at once, and there is no way to control if writes to a
|
|
+cached area have write-through or write-back semantics. In fact, the
|
|
+cache command can always fail and still be compliant, and success
|
|
+might not guarantee a performance gain.
|
|
+
|
|
+If this callback is omitted, then the results of C<.can_cache>
|
|
+determine whether nbdkit will reject cache requests, treat them as
|
|
+instant success, or emulate caching by calling C<.pread> over the same
|
|
+region and ignoring the results.
|
|
|
|
This function will not be called if C<.can_cache> did not return
|
|
-C<NBDKIT_CACHE_NATIVE>. The parameter C<flags> exists in case of
|
|
-future NBD protocol extensions; at this time, it will be 0 on input. A
|
|
-plugin must fail this function if C<flags> includes an unrecognized
|
|
-flag, as that may indicate a requirement that the plugin comply must
|
|
-with a specific caching semantic.
|
|
+C<NBDKIT_CACHE_NATIVE>.
|
|
+
|
|
+The C<flags> parameter exists in case of future NBD protocol
|
|
+extensions; at this time, it will be 0 on input. A plugin must fail
|
|
+this function if C<flags> includes an unrecognized flag, as that may
|
|
+indicate a requirement that the plugin comply must with a specific
|
|
+caching semantic.
|
|
|
|
If there is an error, C<.cache> should call C<nbdkit_error> with an
|
|
error message, and C<nbdkit_set_error> to record an appropriate error
|
|
--
|
|
2.31.1
|
|
|