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

=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>

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