[Libguestfs] [nbdkit PATCH] noextents: Document use case with tmpfs

[Eric Blake]

tmpfs has a known bug of O(n^2) behavior with lseek(SEEK_HOLE); this
is one situation where the noextents filter can come in handy to avoid
the performance penalty of exposing accurate extents.

Signed-off-by: Eric Blake <eblake at redhat.com>
---
 filters/noextents/nbdkit-noextents-filter.pod | 7 ++++++-
 plugins/file/nbdkit-file-plugin.pod           | 9 ++++++++-
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/filters/noextents/nbdkit-noextents-filter.pod b/filters/noextents/nbdkit-noextents-filter.pod
index aa2e9e2..46f6bdb 100644
--- a/filters/noextents/nbdkit-noextents-filter.pod
+++ b/filters/noextents/nbdkit-noextents-filter.pod
@@ -13,6 +13,10 @@ client to detect sparse regions of the underlying disk.
 C<nbdkit-noextents-filter> disables this so that the plugin appears to
 be fully allocated.

+This filter can be useful when combined with L<nbdkit-file-plugin(1)>
+serving a file from a file system known to have poor C<lseek(2)>
+performance (C<tmpfs> is known to be one such system).
+
 =head1 PARAMETERS

 There are no parameters specific to nbdkit-noextents-filter.  Any
@@ -23,7 +27,8 @@ plugin in the normal way.

 L<nbdkit(1)>,
 L<nbdkit-filter(3)>,
-L<nbdkit-nozero-filter(1)>.
+L<nbdkit-nozero-filter(1)>,
+L<nbdkit-file-plugin(1)>.

 =head1 AUTHORS

diff --git a/plugins/file/nbdkit-file-plugin.pod b/plugins/file/nbdkit-file-plugin.pod
index d34a638..9241418 100644
--- a/plugins/file/nbdkit-file-plugin.pod
+++ b/plugins/file/nbdkit-file-plugin.pod
@@ -15,6 +15,12 @@ It serves the named C<FILENAME> over NBD.  Local block devices

 To concatenate multiple files, use L<nbdkit-split-plugin(1)>.

+If you want to expose a file that resides on a file system known to
+have poor C<lseek(2)> performance when searching for holes (C<tmpfs>
+is known to be one such file system), you can use
+L<nbdkit-noextents-filter(1)> to avoid the penalty of probing for
+holes.
+
 =head1 PARAMETERS

 =over 4
@@ -88,7 +94,8 @@ or block device efficiently or not.
 L<nbdkit(1)>,
 L<nbdkit-plugin(3)>,
 L<nbdkit-split-plugin(1)>,
-L<nbdkit-partitioning-plugin(1)>.
+L<nbdkit-partitioning-plugin(1)>,
+L<nbdkit-noextents-filter(1)>.

 =head1 AUTHORS

-- 
2.20.1