[Libguestfs] [nbdkit PATCH v3 15/16] multi-conn: New filter

[Eric Blake]

On 3/9/21 8:59 AM, Richard W.M. Jones wrote:
> On Fri, Mar 05, 2021 at 05:31:19PM -0600, Eric Blake wrote:
>> Implement a TODO item of emulating multi-connection consistency via
>> multiple plugin flush calls to allow a client to assume that a flush
>> on a single connection is good enough.  This also gives us some
>> fine-tuning over whether to advertise the bit, including some setups
>> that are unsafe but may be useful in timing tests.
>>
>> Testing is interesting: I used the sh plugin to implement a server
>> that intentionally keeps a per-connection cache.
>>
>> Note that this filter assumes that multiple connections will still
>> share the same data (other than caching effects); effects are not
>> guaranteed when trying to mix it with more exotic plugins like info
>> that violate that premise.
>> ---

>> +++ b/filters/cache/nbdkit-cache-filter.pod
>> @@ -41,7 +41,9 @@ an explicit flush is done by the client.
>>
>>  This is the default caching mode, and is safe if your client issues
>>  flush requests correctly (which is true for modern Linux and other
>> -well-written NBD clients).
>> +well-written NBD clients).  Note that this mode is able to advertise
>> +multi-connection consistency even without the use of
>> +L<nbdkit-multi-conn-filter(1)>.
> 
> I would say this hunk is confusing and unnecessary.  I mean if you
> shouldn't be using --filter=multi-conn, then just don't say anything :-)
> If it really must be mentioned somewhere then probably better to say
> it in the multi-conn man page instead IMHO.

Fair enough; I'll drop this hunk.

>> +++ b/filters/fua/nbdkit-fua-filter.pod
>> @@ -16,6 +16,12 @@ This filter can be used to disable FUA and flush requests for speed
>>  server fallbacks, and for evaluating timing differences between proper
>>  use of FUA compared to a full flush.
>>
>> +Note that by default, the NBD protocol does not guarantee that the use
>> +of FUA from one connection will be visible from another connection
>> +unless the server advertised NBD_FLAG_MULTI_CONN.  You may wish to
>> +combine this filter with L<nbdkit-multi-conn-filter(1)> if you plan on
>> +making multiple connections to the plugin.
> 
> This is a case where mentioning the other filter _is_ a good idea.
> 

>> +++ b/filters/multi-conn/nbdkit-multi-conn-filter.pod
> [...]
> 
> About the rest of the patch, ACK.
> 
> It has to be said I did find the documentation a bit hard to follow.
> If you push this I may follow up with my own documentation fixes (I'll
> run it by you first though).

I'm open to improvements.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org