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

[Richard W.M. Jones]

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).

> @@ -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!)

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-builder quickly builds VMs from scratch
http://libguestfs.org/virt-builder.1.html