[Libguestfs] [libnbd PATCH] api: Allow completion callbacks to auto-retire
Richard W.M. Jones
rjones at redhat.com
Wed Jul 24 12:36:51 UTC 2019
On Tue, Jul 23, 2019 at 03:30:16PM -0500, Eric Blake wrote:
> diff --git a/generator/generator b/generator/generator
> index fdacd71..e0a2805 100755
> --- a/generator/generator
> +++ b/generator/generator
> @@ -1738,9 +1738,9 @@ unique positive 64 bit cookie for this command, or C<-1> on
> error. If this command returns a cookie, then C<callback>
> will be called when the server is done replying,
> although you must still use C<nbd_aio_command_completed> after
> -the callback to retire the command. Note that you must ensure
> -C<buf> is valid until the command has completed. Other
> -parameters behave as documented in C<nbd_pread>.
> +the callback to retire the command unless the callback returns C<1>.
> +Note that you must ensure C<buf> is valid until the command has
> +completed. Other parameters behave as documented in C<nbd_pread>.
>
> The C<callback> function is called with the same C<user_data> passed to
> this function, C<cookie> set to the return value of this function,
> @@ -1796,8 +1796,8 @@ unique positive 64 bit cookie for this command, or C<-1> on
> error. If this command returns a cookie, then C<callback>
> will be called when the server is done replying,
> although you must still use C<nbd_aio_command_completed> after
> -the callback to retire the command. Other parameters behave as
> -documented in C<nbd_pread_structured>.
> +the callback to retire the command unless the callback returns C<1>.
> +Other parameters behave as documented in C<nbd_pread_structured>.
>
> The C<callback> function is called with the same C<user_data> passed to
> this function, C<cookie> set to the return value of this function,
There's quite a lot of duplicated documentation here. There are two
approaches to deduplicating it:
(1) Add a section in the main manual (docs/libnbd.pod):
=head1 CALLBACKS
...
=head2 Completion callbacks
common text here
and link to it from the longdesc using "L<libnbd(3)/Completion callbacks>"
(2) Put the common text in an OCaml string and interpolate it into the
longdesc in the generator:
let completion_text = "\
common text here
";
...
"function", ...
longdesc = "\
normal description
" ^ completion_text;
The rest of the patch is fine.
Rich.
--
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
Fedora Windows cross-compiler. Compile Windows programs, test, and
build Windows installers. Over 100 libraries supported.
http://fedoraproject.org/wiki/MinGW
More information about the Libguestfs
mailing list