filters/nocache/nbdkit-nocache-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-nocache-filter - nbdkit nocache filter
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=nocache plugin [cachemode=MODE] [plugin-args...]
   8
   9 =head1 DESCRIPTION
  10
  11 C<nbdkit-nocache-filter> is a filter that intentionally disables
  12 efficient handling of advisory client cache requests across the NBD
  13 protocol.  It is mainly useful for evaluating timing differences to
  14 determine the impact of caching requests.
  15
  16 Note that the effects of this filter (in crippling handling of client
  17 cache requests) is somewhat orthogonal from that of the
  18 L<nbdkit-cache-filter(1)> (adding local caching of client read/write
  19 requests); the two filters can be run together to experiment with
  20 timings.
  21
  22 =head1 PARAMETERS
  23
  24 =over 4
  25
  26 =item B<cachemode=none>
  27
  28 =item B<cachemode=emulate>
  29
  30 =item B<cachemode=nop>
  31
  32 Optional, controls which mode the filter will use.  Mode B<none>
  33 (default) means that cache support is not advertised to the
  34 client. Mode B<emulate> means that cache support is emulated by the
  35 filter using the plugin's C<pread> callback, regardless of whether the
  36 plugin itself implemented the C<cache> callback. Mode B<nop> means
  37 that cache requests are always accepted and immediately ignored,
  38 rather than having any actual impact.
  39
  40 =back
  41
  42 =head1 EXAMPLES
  43
  44 Serve the file F<disk.img>, but prevent C<NBD_CMD_CACHE> requests
  45 altogether, to get a baseline timing of behavior when the client is
  46 unable to make cache requests:
  47
  48  nbdkit --filter=nocache file disk.img
  49
  50 Serve the file F<disk.img>, but with cache requests silently ignored,
  51 rather than being forwarded on to the file plugin (which attempts to
  52 use L<posix_fadvise(3)>), to compare against the timings without the
  53 filter and determine whether the file plugin caching was worthwhile:
  54
  55  nbdkit --filter=nocache file disk.img cachemode=nop
  56
  57 =head1 FILES
  58
  59 =over 4
  60
  61 =item F<$filterdir/nbdkit-nocache-filter.so>
  62
  63 The filter.
  64
  65 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
  66
  67 =back
  68
  69 =head1 VERSION
  70
  71 C<nbdkit-nocache-filter> first appeared in nbdkit 1.14.
  72
  73 =head1 SEE ALSO
  74
  75 L<nbdkit(1)>,
  76 L<nbdkit-file-plugin(1)>,
  77 L<nbdkit-filter(3)>,
  78 L<nbdkit-cache-filter(1)>,
  79 L<nbdkit-fua-filter(1)>,
  80 L<nbdkit-multi-conn-filter(1)>,
  81 L<nbdkit-noextents-filter(1)>,
  82 L<nbdkit-noparallel-filter(1)>,
  83 L<nbdkit-nozero-filter(1)>.
  84
  85 =head1 AUTHORS
  86
  87 Eric Blake
  88
  89 =head1 COPYRIGHT
  90
  91 Copyright Red Hat