[Libguestfs] [PATCH libnbd proposal] api: Add semi-private function for freeing persistent data.

[Richard W.M. Jones]

This adds a C-only semi-private function for freeing various types of
persistent data passed to libnbd.

There are some similarities with nbd_add_close_callback which we
removed in commit 7f191b150b52ed50098976309a6af883d245fc56.
---
 generator/generator | 46 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/generator/generator b/generator/generator
index 55c4dfc..0ea6b61 100755
--- a/generator/generator
+++ b/generator/generator
@@ -3284,6 +3284,7 @@ let generate_lib_libnbd_syms () =
       pr "LIBNBD_%d.%d {\n" major minor;
       pr "  global:\n";
       if (major, minor) = (1, 0) then (
+        pr "    nbd_add_free_callback;\n";
         pr "    nbd_create;\n";
         pr "    nbd_close;\n";
         pr "    nbd_get_errno;\n";
@@ -3581,6 +3582,12 @@ let generate_include_libnbd_h () =
   pr "extern int nbd_get_errno (void);\n";
   pr "#define LIBNBD_HAVE_NBD_GET_ERRNO 1\n";
   pr "\n";
+  pr "typedef void (*nbd_free_callback) (void *ptr);\n";
+  pr "extern int nbd_add_free_callback (struct nbd_handle *h,\n";
+  pr "                                  nbd_free_callback cb,\n";
+  pr "                                  void *ptr);\n";
+  pr "#define LIBNBD_HAVE_NBD_ADD_FREE_CALLBACK 1\n";
+  pr "\n";
   print_closure_typedefs ();
   List.iter (
     fun (name, { args; optargs; ret }) ->
@@ -4005,6 +4012,45 @@ C<E<lt>errno.hE<gt>>.
   List.iter print_api handle_calls;
 
   pr "\
+=head1 FREE CALLBACKS
+
+B<Note:> The API described in this section is only
+available from C.  It is designed to help when writing
+bindings to libnbd in other programming languages.
+As such it is B<not> covered by the usual API stability
+guarantee offered by other parts of the C API.  Use it with care.
+
+Some pointers passed to libnbd calls are saved in the
+S<C<struct nbd_handle>>.  These include pointers to buffers
+passed to C<nbd_aio_pread>, C<nbd_aio_pwrite>, etc.,
+and pointers to the C<user_data> for callbacks.  If you
+want to know when it is safe to free these objects then
+you can register a free callback using:
+
+ typedef void (*nbd_free_callback) (void *ptr);
+ int nbd_add_free_callback (struct nbd_handle *h,
+                            nbd_free_callback cb,
+                            void *ptr);
+
+C<ptr> is a pointer to the object (ie. the buffer or
+callback C<user_data>).  C<cb (ptr)> is called when libnbd
+no longer holds a reference to that object.
+
+To illustrate how this works with an example:
+
+ struct my_user_data *my_user_data;
+ void *buf;
+ 
+ my_user_data = malloc (sizeof *my_user_data);
+ buf = malloc (512);
+ nbd_add_free_callback (nbd, free, my_user_data);
+ nbd_add_free_callback (nbd, free, buf);
+ nbd_aio_pwrite_callback (nbd, buf, 512, 0,
+                          write_completed, my_user_data, 0);
+
+This would free both C<my_user_data> and C<buf> once libnbd
+has finished with them.
+
 =head1 SEE ALSO
 
 L<libnbd(3)>.
-- 
2.22.0