1nbdkit-readahead-filter(1)          NBDKIT          nbdkit-readahead-filter(1)
2
3
4

NAME

6       nbdkit-readahead-filter - prefetch data ahead of sequential reads
7

SYNOPSIS

9        nbdkit --filter=readahead PLUGIN
10
11        nbdkit --filter=readahead --filter=cache PLUGIN
12
13        nbdkit --filter=readahead --filter=cow PLUGIN cow-on-cache=true
14

DESCRIPTION

16       "nbdkit-readahead-filter" is a filter that prefetches data when the
17       client is reading.
18
19       When the client issues a read, this filter issues a parallel prefetch
20       (".cache") for subsequent data.  Plugins which support this command
21       will prefetch the data, making sequential reads faster.  For plugins
22       which do not support this command, you can inject
23       nbdkit-cache-filter(1) below (after) this filter, giving approximately
24       the same effect.  nbdkit-cow-filter(1) can be used instead of nbdkit-
25       cache-filter, if you add the "cow-on-cache=true" option.
26
27       The filter uses a simple adaptive algorithm which accelerates
28       sequential reads and requires no further configuration.
29
30       A similar filter is nbdkit-scan-filter(1) which reads ahead over the
31       whole disk, useful if you know that the client will be reading
32       sequentially across most or all of the disk.
33
34   Limitations
35       In a number of significant cases this filter will do nothing.  The
36       filter will print a warning message if this happens.
37
38       Thread model must be parallel
39           For example nbdkit-curl-plugin(1) only supports
40           "serialize_requests", and so this filter cannot perform prefetches
41           in parallel with the read requests.
42
43           We may be able to lift this restriction in future.
44
45       Underlying filters or plugin must support ".cache" (prefetch)
46           Very many plugins do not have the concept of prefetching and/or do
47           not implement the ".cache" callback, and so there is no way for
48           this filter to issue prefetches.
49
50           You can usually get around this by adding --filter=cache after this
51           filter as explained above.  It may be necessary to limit the total
52           size of the cache (see "CACHE MAXIMUM SIZE" in
53           nbdkit-cache-filter(1)).
54
55       Clients and kernels may do readahead already
56           It may be the case that NBD clients are already issuing
57           "NBD_CMD_CACHE" (NBD prefetch) commands.  It may also be the case
58           that your plugin is using local file functions where the kernel is
59           doing readahead.  In such cases this filter is not necessary and
60           may be pessimal.
61

PARAMETERS

63       There are no parameters specific to nbdkit-readahead-filter.  Any
64       parameters are passed through to and processed by the underlying plugin
65       in the normal way.
66

FILES

68       $filterdir/nbdkit-readahead-filter.so
69           The filter.
70
71           Use "nbdkit --dump-config" to find the location of $filterdir.
72

VERSION

74       "nbdkit-readahead-filter" first appeared in nbdkit 1.12.
75

SEE ALSO

77       nbdkit(1), nbdkit-cache-filter(1), nbdkit-cow-filter(1),
78       nbdkit-file-plugin(1), nbdkit-retry-filter(1), nbdkit-scan-filter(1),
79       nbdkit-torrent-plugin(1), nbdkit-vddk-plugin(1), nbdkit-filter(3),
80       qemu-img(1).
81

AUTHORS

83       Richard W.M. Jones
84

86       Copyright (C) 2019-2022 Red Hat Inc.
87

LICENSE

89       Redistribution and use in source and binary forms, with or without
90       modification, are permitted provided that the following conditions are
91       met:
92
93       •   Redistributions of source code must retain the above copyright
94           notice, this list of conditions and the following disclaimer.
95
96       •   Redistributions in binary form must reproduce the above copyright
97           notice, this list of conditions and the following disclaimer in the
98           documentation and/or other materials provided with the
99           distribution.
100
101       •   Neither the name of Red Hat nor the names of its contributors may
102           be used to endorse or promote products derived from this software
103           without specific prior written permission.
104
105       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
106       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
107       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
108       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
109       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
110       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
111       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
112       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
113       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
114       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
115       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
116
117
118
119nbdkit-1.32.5                     2023-01-03        nbdkit-readahead-filter(1)
Impressum