Libguestfs - Aug 2019 - [PATCH libnbd] api: Rename nbd_aio_*_callback to nbd_aio_*.

This applies on top of the OClosure v2 series posted a few
minutes ago.

Rich.

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.
---
 docs/libnbd.pod                               |   9 +-
 examples/batched-read-write.c                 |   5 +-
 examples/glib-main-loop.c                     |  12 +-
 examples/strict-structured-reads.c            |   6 +-
 examples/threaded-reads-and-writes.c          |   4 +-
 generator/generator                           | 184 ++++--------------
 lib/rw.c                                      | 139 ++++---------
 ocaml/examples/asynch_copy.ml                 |   4 +-
 .../test_505_aio_pread_structured_callback.ml |   8 +-
 ocaml/tests/test_590_aio_copy.ml              |   4 +-
 python/t/505-aio-pread-callback.py            |  24 +--
 python/t/510-aio-pwrite.py                    |   2 +-
 tests/aio-parallel-load.c                     |   4 +-
 tests/aio-parallel.c                          |   4 +-
 tests/closure-lifetimes.c                     |  12 +-
 tests/errors.c                                |   6 +-
 tests/server-death.c                          |   6 +-
 17 files changed, 123 insertions(+), 310 deletions(-)

diff --git a/docs/libnbd.pod b/docs/libnbd.pod
index 51b1a03..aeecaee 100644
--- a/docs/libnbd.pod
+++ 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
+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
-these functions while processing.
+C<nbd_set_debug_callback>, C<nbd_aio_pread>).  Libnbd can call
these
+functions while processing.
 
 Callbacks have an opaque C<void *user_data> pointer.  This is passed
 as the second parameter to the callback.  The opaque pointer is only
diff --git a/examples/batched-read-write.c b/examples/batched-read-write.c
index d39a1e5..378c2e0 100644
--- a/examples/batched-read-write.c
+++ b/examples/batched-read-write.c
@@ -52,12 +52,13 @@ try_deadlock (void *arg)
   int r;
 
   /* Issue commands. */
-  cookies[0] = nbd_aio_pread (nbd, in, packetsize, 0, 0);
+  cookies[0] = nbd_aio_pread (nbd, in, packetsize, 0,
+                              NULL, NULL, 0);
   if (cookies[0] == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     goto error;
   }
-  cookies[1] = nbd_aio_pwrite (nbd, out, packetsize, packetsize, 0);
+  cookies[1] = nbd_aio_pwrite (nbd, out, packetsize, packetsize, NULL, NULL,
0);
   if (cookies[1] == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     goto error;
diff --git a/examples/glib-main-loop.c b/examples/glib-main-loop.c
index 05a59e3..7b4d215 100644
--- a/examples/glib-main-loop.c
+++ b/examples/glib-main-loop.c
@@ -382,9 +382,9 @@ read_data (gpointer user_data)
   nr_buffers++;
   posn += BUFFER_SIZE;
 
-  if (nbd_aio_pread_callback (gssrc->nbd, buffers[i].data,
-                              BUFFER_SIZE, buffers[i].offset,
-                              finished_read, &buffers[i], 0) == -1) {
+  if (nbd_aio_pread (gssrc->nbd, buffers[i].data,
+                     BUFFER_SIZE, buffers[i].offset,
+                     finished_read, &buffers[i], 0) == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }
@@ -426,9 +426,9 @@ write_data (gpointer user_data)
 
   assert (buffer->state == BUFFER_READ_COMPLETED);
   buffer->state = BUFFER_WRITING;
-  if (nbd_aio_pwrite_callback (gsdest->nbd, buffer->data,
-                               BUFFER_SIZE, buffer->offset,
-                               finished_write, buffer, 0) == -1) {
+  if (nbd_aio_pwrite (gsdest->nbd, buffer->data,
+                      BUFFER_SIZE, buffer->offset,
+                      finished_write, buffer, 0) == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }
diff --git a/examples/strict-structured-reads.c
b/examples/strict-structured-reads.c
index b3880b7..4bc63b8 100644
--- a/examples/strict-structured-reads.c
+++ b/examples/strict-structured-reads.c
@@ -235,9 +235,9 @@ main (int argc, char *argv[])
     *r = (struct range) { .first = offset, .last = offset + maxsize, };
     *d = (struct data) { .offset = offset, .count = maxsize, .flags = flags,
                          .remaining = r, };
-    if (nbd_aio_pread_structured_callback (nbd, buf, sizeof buf, offset,
-                                           read_chunk, d, read_verify, d,
-                                           flags) == -1) {
+    if (nbd_aio_pread_structured (nbd, buf, sizeof buf, offset,
+                                  read_chunk, d, read_verify, d,
+                                  flags) == -1) {
       fprintf (stderr, "%s\n", nbd_get_error ());
       exit (EXIT_FAILURE);
     }
diff --git a/examples/threaded-reads-and-writes.c
b/examples/threaded-reads-and-writes.c
index 85d6e42..7626a02 100644
--- a/examples/threaded-reads-and-writes.c
+++ b/examples/threaded-reads-and-writes.c
@@ -252,9 +252,9 @@ start_thread (void *arg)
       offset = rand () % (exportsize - size);
       cmd = rand () & 1;
       if (cmd == 0)
-        cookie = nbd_aio_pwrite (nbd, buf, size, offset, 0);
+        cookie = nbd_aio_pwrite (nbd, buf, size, offset, NULL, NULL, 0);
       else
-        cookie = nbd_aio_pread (nbd, buf, size, offset, 0);
+        cookie = nbd_aio_pread (nbd, buf, size, offset, NULL, NULL, 0);
       if (cookie == -1) {
         fprintf (stderr, "%s\n", nbd_get_error ());
         goto error;
diff --git a/generator/generator b/generator/generator
index d76eeea..b713b43 100755
--- a/generator/generator
+++ b/generator/generator
@@ -1829,108 +1829,60 @@ on the connection.";
   };
 
   "aio_pread", {
-    default_call with
-    args = [ BytesPersistOut ("buf", "count"); UInt64
"offset" ];
-    optargs = [ OFlags ("flags", cmd_flags) ];
-    ret = RInt64;
-    permitted_states = [ Connected ];
-    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.  To check if the command completed, call
-C<nbd_aio_command_completed>, or use C<nbd_aio_pread_callback>.
-Note that you must ensure C<buf> is valid until the command
-has completed.  Other parameters behave as documented in
-C<nbd_pread>.";
-  };
-
-  "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>.";
   };
 
   "aio_pread_structured", {
-    default_call with
-    args = [ BytesPersistOut ("buf", "count"); UInt64
"offset";
-             Closure chunk_closure ];
-    optargs = [ OFlags ("flags", cmd_flags) ];
-    ret = RInt64;
-    permitted_states = [ Connected ];
-    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.  To check if the command completed, call
-C<nbd_aio_command_completed>, or use
-C<nbd_aio_pread_structured_callback>.  Parameters behave as
-documented in C<nbd_pread_structured>.";
-  };
-
-  "aio_pread_structured_callback", {
     default_call with
     args = [ BytesPersistOut ("buf", "count"); UInt64
"offset";
              Closure chunk_closure ];
     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>.
 
 Other parameters behave as documented in C<nbd_pread_structured>.";
   };
 
   "aio_pwrite", {
-    default_call with
-    args = [ BytesPersistIn ("buf", "count"); UInt64
"offset" ];
-    optargs = [ OFlags ("flags", cmd_flags) ];
-    ret = RInt64;
-    permitted_states = [ Connected ];
-    shortdesc = "write to the NBD server";
-    longdesc = "\
-Issue a write command to the NBD server.  This returns the
-unique positive 64 bit cookie for this command, or C<-1> on
-error.  To check if the command completed, call
-C<nbd_aio_command_completed>, or use C<nbd_aio_pwrite_callback>.
-Note that you must ensure C<buf> is valid until the command
-has completed.  Other parameters behave as documented in
-C<nbd_pwrite>.";
-  };
-
-  "aio_pwrite_callback", {
     default_call with
     args = [ BytesPersistIn ("buf", "count"); UInt64
"offset" ];
     optargs = [ OClosure completion_closure; OFlags ("flags",
cmd_flags) ];
     ret = RInt64;
     permitted_states = [ Connected ];
-    shortdesc = "write to the NBD server, with callback on
completion";
+    shortdesc = "write to the NBD server";
     longdesc = "\
 Issue a write 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_pwrite>.";
@@ -1960,164 +1912,96 @@ however, C<nbd_shutdown> will call this function
if appropriate.";
   };
 
   "aio_flush", {
-    default_call with
-    args = []; optargs = [ OFlags ("flags", cmd_flags) ]; ret =
RInt64;
-    permitted_states = [ Connected ];
-    shortdesc = "send flush command to the NBD server";
-    longdesc = "\
-Issue the flush command to the NBD server.  This returns the
-unique positive 64 bit cookie for this command, or C<-1> on
-error.  To check if the command completed, call
-C<nbd_aio_command_completed>, or use C<nbd_aio_flush_callback>.
-Parameters behave as documented in C<nbd_flush>.";
-  };
-
-  "aio_flush_callback", {
     default_call with
     args = [];
     optargs = [ OClosure completion_closure; OFlags ("flags",
cmd_flags) ];
     ret = RInt64;
     permitted_states = [ Connected ];
-    shortdesc = "send flush command to the NBD server, with callback on
completion";
+    shortdesc = "send flush command to the NBD server";
     longdesc = "\
 Issue the flush 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>.
 
 Other parameters behave as documented in C<nbd_flush>.";
   };
 
   "aio_trim", {
-    default_call with
-    args = [ UInt64 "count"; UInt64 "offset" ];
-    optargs = [ OFlags ("flags", cmd_flags) ];
-    ret = RInt64;
-    permitted_states = [ Connected ];
-    shortdesc = "send trim command to the NBD server";
-    longdesc = "\
-Issue a trim command to the NBD server.  This returns the
-unique positive 64 bit cookie for this command, or C<-1> on
-error.  To check if the command completed, call
-C<nbd_aio_command_completed>, or use C<nbd_aio_trim_callback>.
-Parameters behave as documented in C<nbd_trim>.";
-  };
-
-  "aio_trim_callback", {
     default_call with
     args = [ UInt64 "count"; UInt64 "offset" ];
     optargs = [ OClosure completion_closure; OFlags ("flags",
cmd_flags) ];
     ret = RInt64;
     permitted_states = [ Connected ];
-    shortdesc = "send trim command to the NBD server, with callback on
completion";
+    shortdesc = "send trim command to the NBD server";
     longdesc = "\
 Issue a trim 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>.
 
 Other parameters behave as documented in C<nbd_trim>.";
   };
 
   "aio_cache", {
-    default_call with
-    args = [ UInt64 "count"; UInt64 "offset" ];
-    optargs = [ OFlags ("flags", cmd_flags) ];
-    ret = RInt64;
-    permitted_states = [ Connected ];
-    shortdesc = "send cache (prefetch) command to the NBD server";
-    longdesc = "\
-Issue the cache (prefetch) command to the NBD server.  This
-returns the unique positive 64 bit cookie for this command, or
-C<-1> on error.  To check if the command completed, call
-C<nbd_aio_command_completed>, or use C<nbd_aio_cache_callback>.
-Parameters behave as documented in C<nbd_cache>.";
-  };
-
-  "aio_cache_callback", {
     default_call with
     args = [ UInt64 "count"; UInt64 "offset" ];
     optargs = [ OClosure completion_closure; OFlags ("flags",
cmd_flags) ];
     ret = RInt64;
     permitted_states = [ Connected ];
-    shortdesc = "send cache (prefetch) command to the NBD server, with
callback on completion";
+    shortdesc = "send cache (prefetch) command to the NBD server";
     longdesc = "\
 Issue the cache (prefetch) 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>.
 
 Other parameters behave as documented in C<nbd_cache>.";
   };
 
   "aio_zero", {
-    default_call with
-    args = [ UInt64 "count"; UInt64 "offset" ];
-    optargs = [ OFlags ("flags", cmd_flags) ];
-    ret = RInt64;
-    permitted_states = [ Connected ];
-    shortdesc = "send write zeroes command to the NBD server";
-    longdesc = "\
-Issue a write zeroes command to the NBD server.  This returns the
-unique positive 64 bit cookie for this command, or C<-1> on
-error.  To check if the command completed, call
-C<nbd_aio_command_completed>, or use C<nbd_aio_zero_callback>.
-Parameters behave as documented in C<nbd_zero>.";
-  };
-
-  "aio_zero_callback", {
     default_call with
     args = [ UInt64 "count"; UInt64 "offset" ];
     optargs = [ OClosure completion_closure; OFlags ("flags",
cmd_flags) ];
     ret = RInt64;
     permitted_states = [ Connected ];
-    shortdesc = "send write zeroes command to the NBD server, with
callback on completion";
+    shortdesc = "send write zeroes command to the NBD server";
     longdesc = "\
 Issue a write zeroes 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>.
 
 Other parameters behave as documented in C<nbd_zero>.";
   };
 
   "aio_block_status", {
-    default_call with
-    args = [ UInt64 "count"; UInt64 "offset"; Closure
extent_closure ];
-    optargs = [ OFlags ("flags", cmd_flags) ];
-    ret = RInt64;
-    permitted_states = [ Connected ];
-    shortdesc = "send block status command to the NBD server";
-    longdesc = "\
-Send the block status command to the NBD server.  This returns the
-unique positive 64 bit cookie for this command, or C<-1> on
-error.  To check if the command completed, call
-C<nbd_aio_command_completed>, or use
C<nbd_aio_block_status_callback>.
-Parameters behave as documented in C<nbd_block_status>.";
-  };
-
-  "aio_block_status_callback", {
     default_call with
     args = [ UInt64 "count"; UInt64 "offset"; Closure
extent_closure ];
     optargs = [ OClosure completion_closure; OFlags ("flags",
cmd_flags) ];
     ret = RInt64;
     permitted_states = [ Connected ];
-    shortdesc = "send block status command to the NBD server, with
callback on completion";
+    shortdesc = "send block status command to the NBD server";
     longdesc = "\
 Send the block status 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>.
 
 Other parameters behave as documented in C<nbd_block_status>.";
   };
@@ -2287,9 +2171,7 @@ true then the command was successful and it has been
retired.
 Return false if the command is still in flight.  This can also
 fail with an error in case the command failed (in this case
 the command is also retired).  A command is retired either via
-this command, or by using a completion callback which returns
-C<1> (completion callbacks are registered via
-C<nbd_aio_pread_callback> and similar).
+this command, or by using a completion callback which returns C<1>.
 
 The C<cookie> parameter is the positive unique 64 bit cookie
 for the command, as returned by a call such as C<nbd_aio_pread>.";
diff --git a/lib/rw.c b/lib/rw.c
index 50ba23d..dbd4e8c 100644
--- a/lib/rw.c
+++ b/lib/rw.c
@@ -49,7 +49,7 @@ nbd_unlocked_pread (struct nbd_handle *h, void *buf,
 {
   int64_t cookie;
 
-  cookie = nbd_unlocked_aio_pread (h, buf, count, offset, flags);
+  cookie = nbd_unlocked_aio_pread (h, buf, count, offset, NULL, NULL, flags);
   if (cookie == -1)
     return -1;
 
@@ -66,7 +66,8 @@ nbd_unlocked_pread_structured (struct nbd_handle *h, void
*buf,
   int64_t cookie;
 
   cookie = nbd_unlocked_aio_pread_structured (h, buf, count, offset,
-                                              chunk, user_data, flags);
+                                              chunk, user_data,
+                                              NULL, NULL, flags);
   if (cookie == -1)
     return -1;
 
@@ -80,7 +81,7 @@ nbd_unlocked_pwrite (struct nbd_handle *h, const void *buf,
 {
   int64_t cookie;
 
-  cookie = nbd_unlocked_aio_pwrite (h, buf, count, offset, flags);
+  cookie = nbd_unlocked_aio_pwrite (h, buf, count, offset, NULL, NULL, flags);
   if (cookie == -1)
     return -1;
 
@@ -93,7 +94,7 @@ nbd_unlocked_flush (struct nbd_handle *h, uint32_t flags)
 {
   int64_t cookie;
 
-  cookie = nbd_unlocked_aio_flush (h, flags);
+  cookie = nbd_unlocked_aio_flush (h, NULL, NULL, flags);
   if (cookie == -1)
     return -1;
 
@@ -107,7 +108,7 @@ nbd_unlocked_trim (struct nbd_handle *h,
 {
   int64_t cookie;
 
-  cookie = nbd_unlocked_aio_trim (h, count, offset, flags);
+  cookie = nbd_unlocked_aio_trim (h, count, offset, NULL, NULL, flags);
   if (cookie == -1)
     return -1;
 
@@ -121,7 +122,7 @@ nbd_unlocked_cache (struct nbd_handle *h,
 {
   int64_t cookie;
 
-  cookie = nbd_unlocked_aio_cache (h, count, offset, flags);
+  cookie = nbd_unlocked_aio_cache (h, count, offset, NULL, NULL, flags);
   if (cookie == -1)
     return -1;
 
@@ -135,7 +136,7 @@ nbd_unlocked_zero (struct nbd_handle *h,
 {
   int64_t cookie;
 
-  cookie = nbd_unlocked_aio_zero (h, count, offset, flags);
+  cookie = nbd_unlocked_aio_zero (h, count, offset, NULL, NULL, flags);
   if (cookie == -1)
     return -1;
 
@@ -152,7 +153,7 @@ nbd_unlocked_block_status (struct nbd_handle *h,
   int64_t cookie;
 
   cookie = nbd_unlocked_aio_block_status (h, count, offset, extent, user_data,
-                                          flags);
+                                          NULL, NULL, flags);
   if (cookie == -1)
     return -1;
 
@@ -254,18 +255,10 @@ nbd_internal_command_common (struct nbd_handle *h,
 
 int64_t
 nbd_unlocked_aio_pread (struct nbd_handle *h, void *buf,
-                        size_t count, uint64_t offset, uint32_t flags)
-{
-  return nbd_unlocked_aio_pread_callback (h, buf, count, offset, NULL, NULL,
-                                          flags);
-}
-
-int64_t
-nbd_unlocked_aio_pread_callback (struct nbd_handle *h, void *buf,
-                                 size_t count, uint64_t offset,
-                                 nbd_completion_callback completion,
-                                 void *user_data,
-                                 uint32_t flags)
+                        size_t count, uint64_t offset,
+                        nbd_completion_callback completion,
+                        void *user_data,
+                        uint32_t flags)
 {
   struct command_cb cb = { .completion = completion, .user_data = user_data, };
 
@@ -285,23 +278,11 @@ nbd_unlocked_aio_pread_callback (struct nbd_handle *h,
void *buf,
 int64_t
 nbd_unlocked_aio_pread_structured (struct nbd_handle *h, void *buf,
                                    size_t count, uint64_t offset,
-                                   nbd_chunk_callback chunk, void *user_data,
+                                   nbd_chunk_callback chunk,
+                                   void *read_user_data,
+                                   nbd_completion_callback completion,
+                                   void *callback_user_data,
                                    uint32_t flags)
-{
-  return nbd_unlocked_aio_pread_structured_callback (h, buf, count, offset,
-                                                     chunk, user_data,
-                                                     NULL, NULL,
-                                                     flags);
-}
-
-int64_t
-nbd_unlocked_aio_pread_structured_callback (struct nbd_handle *h, void *buf,
-                                            size_t count, uint64_t offset,
-                                            nbd_chunk_callback chunk,
-                                            void *read_user_data,
-                                            nbd_completion_callback completion,
-                                            void *callback_user_data,
-                                            uint32_t flags)
 {
   struct command_cb cb = { .fn.chunk = chunk,
                            .fn_user_data = read_user_data,
@@ -326,18 +307,9 @@ nbd_unlocked_aio_pread_structured_callback (struct
nbd_handle *h, void *buf,
 int64_t
 nbd_unlocked_aio_pwrite (struct nbd_handle *h, const void *buf,
                          size_t count, uint64_t offset,
+                         nbd_completion_callback completion,
+                         void *user_data,
                          uint32_t flags)
-{
-  return nbd_unlocked_aio_pwrite_callback (h, buf, count, offset, NULL, NULL,
-                                           flags);
-}
-
-int64_t
-nbd_unlocked_aio_pwrite_callback (struct nbd_handle *h, const void *buf,
-                                  size_t count, uint64_t offset,
-                                  nbd_completion_callback completion,
-                                  void *user_data,
-                                  uint32_t flags)
 {
   struct command_cb cb = { .completion = completion, .user_data = user_data, };
 
@@ -362,16 +334,10 @@ nbd_unlocked_aio_pwrite_callback (struct nbd_handle *h,
const void *buf,
 }
 
 int64_t
-nbd_unlocked_aio_flush (struct nbd_handle *h, uint32_t flags)
-{
-  return nbd_unlocked_aio_flush_callback (h, NULL, NULL, flags);
-}
-
-int64_t
-nbd_unlocked_aio_flush_callback (struct nbd_handle *h,
-                                 nbd_completion_callback completion,
-                                 void *user_data,
-                                 uint32_t flags)
+nbd_unlocked_aio_flush (struct nbd_handle *h,
+                        nbd_completion_callback completion,
+                        void *user_data,
+                        uint32_t flags)
 {
   struct command_cb cb = { .completion = completion, .user_data = user_data, };
 
@@ -392,17 +358,9 @@ nbd_unlocked_aio_flush_callback (struct nbd_handle *h,
 int64_t
 nbd_unlocked_aio_trim (struct nbd_handle *h,
                        uint64_t count, uint64_t offset,
+                       nbd_completion_callback completion,
+                       void *user_data,
                        uint32_t flags)
-{
-  return nbd_unlocked_aio_trim_callback (h, count, offset, NULL, NULL, flags);
-}
-
-int64_t
-nbd_unlocked_aio_trim_callback (struct nbd_handle *h,
-                                uint64_t count, uint64_t offset,
-                                nbd_completion_callback completion,
-                                void *user_data,
-                                uint32_t flags)
 {
   struct command_cb cb = { .completion = completion, .user_data = user_data, };
 
@@ -433,17 +391,10 @@ nbd_unlocked_aio_trim_callback (struct nbd_handle *h,
 
 int64_t
 nbd_unlocked_aio_cache (struct nbd_handle *h,
-                        uint64_t count, uint64_t offset, uint32_t flags)
-{
-  return nbd_unlocked_aio_cache_callback (h, count, offset, NULL, NULL, flags);
-}
-
-int64_t
-nbd_unlocked_aio_cache_callback (struct nbd_handle *h,
-                                 uint64_t count, uint64_t offset,
-                                 nbd_completion_callback completion,
-                                 void *user_data,
-                                 uint32_t flags)
+                        uint64_t count, uint64_t offset,
+                        nbd_completion_callback completion,
+                        void *user_data,
+                        uint32_t flags)
 {
   struct command_cb cb = { .completion = completion, .user_data = user_data, };
 
@@ -468,17 +419,9 @@ nbd_unlocked_aio_cache_callback (struct nbd_handle *h,
 int64_t
 nbd_unlocked_aio_zero (struct nbd_handle *h,
                        uint64_t count, uint64_t offset,
+                       nbd_completion_callback completion,
+                       void *user_data,
                        uint32_t flags)
-{
-  return nbd_unlocked_aio_zero_callback (h, count, offset, NULL, NULL, flags);
-}
-
-int64_t
-nbd_unlocked_aio_zero_callback (struct nbd_handle *h,
-                                uint64_t count, uint64_t offset,
-                                nbd_completion_callback completion,
-                                void *user_data,
-                                uint32_t flags)
 {
   struct command_cb cb = { .completion = completion, .user_data = user_data, };
 
@@ -510,23 +453,11 @@ nbd_unlocked_aio_zero_callback (struct nbd_handle *h,
 int64_t
 nbd_unlocked_aio_block_status (struct nbd_handle *h,
                                uint64_t count, uint64_t offset,
-                               nbd_extent_callback extent, void *user_data,
+                               nbd_extent_callback extent,
+                               void *extent_user_data,
+                               nbd_completion_callback completion,
+                               void *callback_user_data,
                                uint32_t flags)
-{
-  return nbd_unlocked_aio_block_status_callback (h, count, offset,
-                                                 extent, user_data,
-                                                 NULL, NULL,
-                                                 flags);
-}
-
-int64_t
-nbd_unlocked_aio_block_status_callback (struct nbd_handle *h,
-                                        uint64_t count, uint64_t offset,
-                                        nbd_extent_callback extent,
-                                        void *extent_user_data,
-                                        nbd_completion_callback completion,
-                                        void *callback_user_data,
-                                        uint32_t flags)
 {
   struct command_cb cb = { .fn.extent = extent,
                            .fn_user_data = extent_user_data,
diff --git a/ocaml/examples/asynch_copy.ml b/ocaml/examples/asynch_copy.ml
index 5aa6e60..8057118 100644
--- a/ocaml/examples/asynch_copy.ml
+++ 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));
       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))
     ) !writes;
     writes := [];
diff --git a/ocaml/tests/test_505_aio_pread_structured_callback.ml
b/ocaml/tests/test_505_aio_pread_structured_callback.ml
index dc0d557..075ec85 100644
--- a/ocaml/tests/test_505_aio_pread_structured_callback.ml
+++ b/ocaml/tests/test_505_aio_pread_structured_callback.ml
@@ -60,7 +60,7 @@ let ()  
   (* First try: succeed in both callbacks *)
   let buf = NBD.Buffer.alloc 512 in
-  let cookie = NBD.aio_pread_structured_callback nbd buf 0_L (chunk 42)
+  let cookie = NBD.aio_pread_structured nbd buf 0_L (chunk 42)
                  ~completion:(callback 42) in
   while not (NBD.aio_command_completed nbd cookie) do
     ignore (NBD.poll nbd (-1))
@@ -72,7 +72,7 @@ let ()  
   (* Second try: fail only during callback *)
   let buf = NBD.Buffer.alloc 512 in
-  let cookie = NBD.aio_pread_structured_callback nbd buf 0_L (chunk 42)
+  let cookie = NBD.aio_pread_structured nbd buf 0_L (chunk 42)
                  ~completion:(callback 43) in
   try
     while not (NBD.aio_command_completed nbd cookie) do
@@ -86,7 +86,7 @@ let ()  
   (* Third try: fail during both *)
   let buf = NBD.Buffer.alloc 512 in
-  let cookie = NBD.aio_pread_structured_callback nbd buf 0_L (chunk 43)
+  let cookie = NBD.aio_pread_structured nbd buf 0_L (chunk 43)
                  ~completion:(callback 44) in
   try
     while not (NBD.aio_command_completed nbd cookie) do
@@ -100,7 +100,7 @@ let ()  
   (* Fourth try: fail only during chunk *)
   let buf = NBD.Buffer.alloc 512 in
-  let cookie = NBD.aio_pread_structured_callback nbd buf 0_L (chunk 43)
+  let cookie = NBD.aio_pread_structured nbd buf 0_L (chunk 43)
                  ~completion:(callback 42) in
   try
     while not (NBD.aio_command_completed nbd cookie) do
diff --git a/ocaml/tests/test_590_aio_copy.ml b/ocaml/tests/test_590_aio_copy.ml
index 18ce389..defb4cb 100644
--- a/ocaml/tests/test_590_aio_copy.ml
+++ 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));
       soff := !soff +^ bs
     );
@@ -82,7 +82,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))
     ) !writes;
     writes := [];
diff --git a/python/t/505-aio-pread-callback.py
b/python/t/505-aio-pread-callback.py
index e552db8..8d71c38 100644
--- a/python/t/505-aio-pread-callback.py
+++ b/python/t/505-aio-pread-callback.py
@@ -44,9 +44,9 @@ def callback (user_data, err):
 
 # First try: succeed in both callbacks
 buf = nbd.Buffer (512)
-cookie = h.aio_pread_structured_callback (buf, 0,
-                                          lambda *args: chunk (42, *args),
-                                          lambda *args: callback (42, *args))
+cookie = h.aio_pread_structured (buf, 0,
+                                 lambda *args: chunk (42, *args),
+                                 lambda *args: callback (42, *args))
 while not (h.aio_command_completed (cookie)):
     h.poll (-1)
 
@@ -58,9 +58,9 @@ assert buf == expected
 
 # Second try: fail only during callback
 buf = nbd.Buffer (512)
-cookie = h.aio_pread_structured_callback (buf, 0,
-                                          lambda *args: chunk (42, *args),
-                                          lambda *args: callback (43, *args))
+cookie = h.aio_pread_structured (buf, 0,
+                                 lambda *args: chunk (42, *args),
+                                 lambda *args: callback (43, *args))
 try:
     while not (h.aio_command_completed (cookie)):
         h.poll (-1)
@@ -70,9 +70,9 @@ except nbd.Error as ex:
 
 # Third try: fail during both
 buf = nbd.Buffer (512)
-cookie = h.aio_pread_structured_callback (buf, 0,
-                                          lambda *args: chunk (43, *args),
-                                          lambda *args: callback (44, *args))
+cookie = h.aio_pread_structured (buf, 0,
+                                 lambda *args: chunk (43, *args),
+                                 lambda *args: callback (44, *args))
 try:
     while not (h.aio_command_completed (cookie)):
         h.poll (-1)
@@ -82,9 +82,9 @@ except nbd.Error as ex:
 
 # Fourth try: fail only during chunk
 buf = nbd.Buffer (512)
-cookie = h.aio_pread_structured_callback (buf, 0,
-                                          lambda *args: chunk (43, *args),
-                                          lambda *args: callback (42, *args))
+cookie = h.aio_pread_structured (buf, 0,
+                                 lambda *args: chunk (43, *args),
+                                 lambda *args: callback (42, *args))
 try:
     while not (h.aio_command_completed (cookie)):
         h.poll (-1)
diff --git a/python/t/510-aio-pwrite.py b/python/t/510-aio-pwrite.py
index 71aa9ba..ded1d10 100644
--- a/python/t/510-aio-pwrite.py
+++ b/python/t/510-aio-pwrite.py
@@ -34,7 +34,7 @@ h.connect_command (["nbdkit", "-s",
"--exit-with-parent", "-v",
                     "file", datafile])
 
 buf1 = nbd.Buffer.from_bytearray (buf)
-cookie = h.aio_pwrite (buf1, 0, nbd.CMD_FLAG_FUA)
+cookie = h.aio_pwrite (buf1, 0, flags=nbd.CMD_FLAG_FUA)
 while not (h.aio_command_completed (cookie)):
     h.poll (-1)
 
diff --git a/tests/aio-parallel-load.c b/tests/aio-parallel-load.c
index 614c22b..1f48324 100644
--- a/tests/aio-parallel-load.c
+++ b/tests/aio-parallel-load.c
@@ -255,11 +255,11 @@ start_thread (void *arg)
       offset = rand () % (EXPORTSIZE - buf_size);
       cmd = rand () & 1;
       if (cmd == 0) {
-        cookie = nbd_aio_pwrite (nbd, buf, buf_size, offset, 0);
+        cookie = nbd_aio_pwrite (nbd, buf, buf_size, offset, NULL, NULL, 0);
         status->bytes_sent += buf_size;
       }
       else {
-        cookie = nbd_aio_pread (nbd, buf, buf_size, offset, 0);
+        cookie = nbd_aio_pread (nbd, buf, buf_size, offset, NULL, NULL, 0);
         status->bytes_received += buf_size;
       }
       if (cookie == -1) {
diff --git a/tests/aio-parallel.c b/tests/aio-parallel.c
index b6a0682..fb4d695 100644
--- a/tests/aio-parallel.c
+++ b/tests/aio-parallel.c
@@ -271,12 +271,12 @@ start_thread (void *arg)
         + (rand () % (status->length[i] - BUFFERSIZE));
       cmd = rand () & 1;
       if (cmd == 0) {
-        cookie = nbd_aio_pwrite (nbd, buf, BUFFERSIZE, offset, 0);
+        cookie = nbd_aio_pwrite (nbd, buf, BUFFERSIZE, offset, NULL, NULL, 0);
         status->bytes_sent += BUFFERSIZE;
         memcpy (&ramdisk[offset], buf, BUFFERSIZE);
       }
       else {
-        cookie = nbd_aio_pread (nbd, buf, BUFFERSIZE, offset, 0);
+        cookie = nbd_aio_pread (nbd, buf, BUFFERSIZE, offset, NULL, NULL, 0);
         status->bytes_received += BUFFERSIZE;
       }
       if (cookie == -1) {
diff --git a/tests/closure-lifetimes.c b/tests/closure-lifetimes.c
index d8ea3f7..60809d4 100644
--- a/tests/closure-lifetimes.c
+++ b/tests/closure-lifetimes.c
@@ -116,9 +116,9 @@ main (int argc, char *argv[])
   if (nbd == NULL) NBD_ERROR;
   if (nbd_connect_command (nbd, nbdkit) == -1) NBD_ERROR;
 
-  cookie = nbd_aio_pread_structured_callback (nbd, buf, sizeof buf, 0,
-                                              read_cb, NULL,
-                                              completion_cb, NULL, 0);
+  cookie = nbd_aio_pread_structured (nbd, buf, sizeof buf, 0,
+                                     read_cb, NULL,
+                                     completion_cb, NULL, 0);
   if (cookie == -1) NBD_ERROR;
   assert (read_cb_free == 0);
   assert (completion_cb_free == 0);
@@ -143,9 +143,9 @@ main (int argc, char *argv[])
   if (nbd == NULL) NBD_ERROR;
   if (nbd_connect_command (nbd, nbdkit_delay) == -1) NBD_ERROR;
 
-  cookie = nbd_aio_pread_structured_callback (nbd, buf, sizeof buf, 0,
-                                              read_cb, NULL,
-                                              completion_cb, NULL, 0);
+  cookie = nbd_aio_pread_structured (nbd, buf, sizeof buf, 0,
+                                     read_cb, NULL,
+                                     completion_cb, NULL, 0);
   if (cookie == -1) NBD_ERROR;
   nbd_kill_command (nbd, 0);
   nbd_close (nbd);
diff --git a/tests/errors.c b/tests/errors.c
index 8a916fe..e442738 100644
--- a/tests/errors.c
+++ b/tests/errors.c
@@ -222,7 +222,7 @@ main (int argc, char *argv[])
     exit (EXIT_FAILURE);
   }
   check (ERANGE, "nbd_pread: ");
-  if (nbd_aio_pwrite (nbd, buf, MAXSIZE, 0, 0) != -1) {
+  if (nbd_aio_pwrite (nbd, buf, MAXSIZE, 0, NULL, NULL, 0) != -1) {
     fprintf (stderr, "%s: test failed: "
              "nbd_aio_pwrite did not fail with oversize request\n",
              argv[0]);
@@ -245,11 +245,11 @@ main (int argc, char *argv[])
    * command at a time and stalls on the first), then queue multiple
    * disconnects.
    */
-  if (nbd_aio_pwrite (nbd, buf, 2 * 1024 * 1024, 0, 0) == -1) {
+  if (nbd_aio_pwrite (nbd, buf, 2 * 1024 * 1024, 0, NULL, NULL, 0) == -1) {
     fprintf (stderr, "%s: %s\n", argv[0], nbd_get_error ());
     exit (EXIT_FAILURE);
   }
-  if (nbd_aio_pwrite (nbd, buf, 2 * 1024 * 1024, 0, 0) == -1) {
+  if (nbd_aio_pwrite (nbd, buf, 2 * 1024 * 1024, 0, NULL, NULL, 0) == -1) {
     fprintf (stderr, "%s: %s\n", argv[0], nbd_get_error ());
     exit (EXIT_FAILURE);
   }
diff --git a/tests/server-death.c b/tests/server-death.c
index 7854527..1559753 100644
--- a/tests/server-death.c
+++ b/tests/server-death.c
@@ -77,13 +77,13 @@ main (int argc, char *argv[])
   /* Issue a read and trim that should not complete yet. Set up the
    * trim to auto-retire via callback.
    */
-  if ((cookie = nbd_aio_pread (nbd, buf, sizeof buf, 0, 0)) == -1) {
+  if ((cookie = nbd_aio_pread (nbd, buf, sizeof buf, 0, NULL, NULL, 0)) == -1)
{
     fprintf (stderr, "%s: test failed: nbd_aio_pread: %s\n", argv[0],
              nbd_get_error ());
     exit (EXIT_FAILURE);
   }
-  if (nbd_aio_trim_callback (nbd, sizeof buf, 0, callback, NULL, 0) == -1) {
-    fprintf (stderr, "%s: test failed: nbd_aio_trim_callback: %s\n",
argv[0],
+  if (nbd_aio_trim (nbd, sizeof buf, 0, callback, NULL, 0) == -1) {
+    fprintf (stderr, "%s: test failed: nbd_aio_trim: %s\n", argv[0],
              nbd_get_error ());
     exit (EXIT_FAILURE);
   }
-- 
2.22.0

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