10:56 a.m.
On 8/13/19 10:37 AM, Richard W.M. Jones wrote:
The original nbd_aio_* (non-callback) functions are removed and
replaced with the renamed callback variants.
This is a simple mechanical change to the API:
(1) Any existing call to nbd_aio_*_callback can simply be renamed to
nbd_aio_*
(2) Any existing call to nbd_aio_* must have two extra NULL parameters
added before the final flags parameter.
In non-C languages, only change (1) is required.
It is still possible to compile for 0.9.6 and this patch simultaneously,
by checking LIBNBD_HAVE_NBD_AIO_PREAD_CALLBACK as a witness of which API
style to use (although it's also just as easy to bump minimum version
requirements to 0.9.7, once we have a release including this and any
other API changes being discussed...).
+++ b/docs/libnbd.pod
@@ -276,9 +276,8 @@ command has completed:
}
For almost all high level synchronous calls (eg. C<nbd_pread>) there
-are two low level asynchronous equivalents (eg. C<nbd_aio_pread> for
-starting a command, and C<nbd_aio_pread_callback> for also registering
-a callback to be invoked right before the command is complete).
+is a low level asynchronous equivalents (eg. C<nbd_aio_pread> for
equivalent
+starting a command).
=head2 glib2 integration
@@ -600,8 +599,8 @@ will use your login name):
=head1 CALLBACKS
Some libnbd calls take function pointers (eg.
-C<nbd_set_debug_callback>, C<nbd_pread_callback>). Libnbd can call
Eww - we had a bogus link (that should have been
nbd_aio_pread_callback). Nice that we fix that as a side effect.
-these functions while processing.
+C<nbd_set_debug_callback>, C<nbd_aio_pread>). Libnbd can call these
+functions while processing.
- "aio_pread_callback", {
default_call with
args = [ BytesPersistOut ("buf", "count"); UInt64
"offset" ];
optargs = [ OClosure completion_closure; OFlags ("flags", cmd_flags) ];
ret = RInt64;
permitted_states = [ Connected ];
- shortdesc = "read from the NBD server, with callback on completion";
+ shortdesc = "read from the NBD server";
longdesc = "\
Issue a read command to the NBD server. This returns the
unique positive 64 bit cookie for this command, or C<-1> on
error.
-When the command completes, C<callback>
-will be invoked as described in L<libnbd(3)/Completion callbacks>.
+To check if the command completed, call C<nbd_aio_command_completed>.
+Or supply the optional C<completion> callback which will be invoked
+as described in L<libnbd(3)/Completion callbacks>.
Note that you must ensure C<buf> is valid until the command has
completed. Other parameters behave as documented in C<nbd_pread>.";
While we're here, should we also mention that C<completion> and
C<completion_user_data> remain valid until the command completes? Or is
that overkill (the function pointer remains valid unless you dlclose()
something providing it; and it's kind of obvious that you want the user
data to remain valid). It may matter more for functions that don't take
a buf (such as nbd_aio_trim).
+++ b/lib/rw.c
Yep, definitely a mechanical conversion.
+++ b/ocaml/examples/asynch_copy.ml
@@ -48,7 +48,7 @@ let asynch_copy src dst =
if !soff < size && NBD.aio_in_flight src < max_reads_in_flight then (
let bs = min bs (size -^ !soff) in
let buf = NBD.Buffer.alloc (Int64.to_int bs) in
- ignore (NBD.aio_pread_callback src buf !soff
+ ignore (NBD.aio_pread src buf !soff
~completion:(read_completed buf !soff));
Pre-existing; but is the indentation off here? (I would have guessed two
fewer spaces, so that ~completion starts just after the ( above)
soff := !soff +^ bs
);
@@ -59,7 +59,7 @@ let asynch_copy src dst =
List.iter (
fun (buf, offset) ->
(* Note the size of the write is implicitly stored in buf. *)
- ignore (NBD.aio_pwrite_callback dst buf offset
+ ignore (NBD.aio_pwrite dst buf offset
~completion:(write_completed buf))
and here
+++ b/ocaml/tests/test_590_aio_copy.ml
@@ -71,7 +71,7 @@ let asynch_copy src dst =
if !soff < size && NBD.aio_in_flight src < max_reads_in_flight then (
let bs = min bs (size -^ !soff) in
let buf = NBD.Buffer.alloc (Int64.to_int bs) in
- ignore (NBD.aio_pread_callback src buf !soff
+ ignore (NBD.aio_pread src buf !soff
~completion:(read_completed buf !soff));
But you are consistent about it, so don't change it if my sense of OCaml
style isn't right :)
ACK with typo fix.
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3226
Virtualization: qemu.org | libvirt.org