[Libguestfs] [nbdkit PATCH v2 13/13] RFC: plugins: Add callbacks for FUA semantics

[Eric Blake]

On 01/19/2018 09:27 AM, Richard W.M. Jones wrote:
> On Fri, Jan 19, 2018 at 07:40:29AM -0600, Eric Blake wrote:
>>  =head1 SYNOPSIS
>>
>> + #define NBDKIT_API_VERSION 2
>> + 
>>   #include <nbdkit-plugin.h>
>>   
>>   #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
>> @@ -51,9 +53,21 @@ L<nbdkit-perl-plugin(3)>,
>>  L<nbdkit-python-plugin(3)>,
>>  L<nbdkit-ruby-plugin(3)>.
>>
>> +=head1 C<#define NBDKIT_API_VERSION>
>> +
>> +Plugins must choose which API version they want to use.  The default
>> +version is 1; but if a plugin defines NBDKIT_API_VERSION to a positive
>> +integer prior to including C<nbdkit-plugin.h>, the signature of
>> +several callbacks is enhanced.  A newer nbdkit will always support
>> +plugins compiled against an older API version, but plugins that opt in
>> +to newer versions require a new enough nbdkit.  For now, the maximum
>> +version is 2, which enables fine-tuned response to client flags
>> +including efficient Forced Unit Access (FUA) on writes.
...
>> +
>>  =head1 C<nbdkit-plugin.h>
>>
>> -All plugins should start by including this header file:
>> +All plugins should start by including this header file, after
>> +optionally choosing an API version:
>>
>>   #include <nbdkit-plugin.h>
> 
> I'm in favour of only documenting the newest API.  Of course we keep
> the old one working, but we don't need to document it any longer.
> 
> This means that each instance of the #include is always preceeded by
> ‘#define NBDKIT_API_VERSION 2’ (or whatever is the latest version).

Okay, that makes the documentation side easier.


> 
>> @@ -442,6 +477,21 @@ recovered from), C<.pwrite> should call C<nbdkit_error> with an error
>>  message, and C<nbdkit_set_error> to record an appropriate error
>>  (unless C<errno> is sufficient), then return C<-1>.
>>
>> +If the plugin can provide efficient Forced Unit Access (FUA) semantics,
>> +it should define C<.pwrite_fua> instead.
>> +
>> +=head2 C<.pwrite_fua>
>> +
>> + int pwrite_fua (void *handle, const void *buf, uint32_t count, uint64_t offset, int fua);
> 
> But in fact the callback is still called ‘pwrite’? (which is good!)

Yeah, you caught me in the middle of rebasing, where I'd made edits at
the top of the file but not throughout - I submitted this patch RFC in
order to speed up your work on plugins interface (now that we've agreed
that the backend interface should pass flags everywhere); I also need to
fix things to rework .pread/.flush to pass flags, so that we don't have
to do another API bump down the road (in other words, since 08ca38ebc0
added flags to all 5 functions, the FUA patches should do likewise, even
if only 3 of the functions have a flag value to use).

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 619 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libguestfs/attachments/20180119/cf7708f5/attachment.sig>