[Libguestfs] [nbdkit PATCH] noextents: Document use case with tmpfs
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(a)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