On 3/12/19 2:52 PM, Richard W.M. Jones wrote:
>> +
>> +Iterate over the extents in order, calling C<fn> for each. C<fn>
>> +should return 0 on success or -1 on failure. If a call to C<fn> fails
>> +then C<nbdkit_extents_foreach> also fails immediately.
>
> Question - should foreach allow the caller to pass in bounds? That is,
> since the plugin can populate 0 - full_size, but where we know the
> client only asked for information on offset - length, it may be more
> efficient to visit just the extents lying within those bounds. (Maybe
> allow -1 as a shortcut rather than an actual end size, when the ending
> offset is less important).
Yes it's a good idea.
It might also be worth a bool parameter to make it easier to implement
the REQ_ONE flag by stopping the iteration after a single call to <fn>,
regardless of whether fn retured 0 or -1? (But there, it's also fairly
easy to write fn to return -1 without calling nbdkit_error, and to use
opaque as a struct that contains the real error code to know whether the
foreach() returning -1 is fatal and worth raising an error or just an
early success path).
If an empty map has a useful default (whether you decide for a default
of HOLE vs. DATA), I suppose that means foreach() will always call fn at
least once for any given bounds, even when the plugin didn't call _add?
> Is it worth an explicit guarantee that foreach() visits extents in
> ascending order, regardless of whether add() was called out of order?
> (Ties us to our implementation where we split/coalesce per add - but
> seems like it can make life easier for filters if we do have that
> guarantee).
Yes, it should always call them "in order" (as it says). Maybe this
isn't clear? Perhaps I should say "in offset order" or something like
that.
"in offset order" helps (as distinct from "in _add() order")
> No documentation of nbdkit_extents_{new,free}?
Yeah I didn't want to document them in nbdkit-plugin.pod, but then
forgot to document them in nbdkit-filter.pod. I believe they should
never be called by plugins (although that's difficult to enforce).
You could enforce by having _new/_free only declared in nbdkit-filter.h
while the others are in nbdkit-common.h. (a plugin can't easily call a
function that isn't declared). But I don't know if we have to go to that
much effort, or go with the simpler use of a comment in nbdkit-common.h
that states something like "these functions are only intended for use in
filters".
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3226
Virtualization:
qemu.org |
libvirt.org