[Libguestfs] [nbdkit PATCH v3 01/16] filters: Slightly reduce promise of nxdata lifetime

[Eric Blake]

We promise (and test-layers verifies) that the pointer value of nxdata
passed to everything from .prepare to .finalize will be the same.  But
the wording was ambiguous on whether that promise extended to the
nxdata of .open as well.  In practice, this had been possible
previously, but will get harder in upcoming patches that want to
switch over to a struct context* that is not determined until after
the next layer has been opened.  So update the wording and test to
match our intent.
---
 docs/nbdkit-filter.pod     | 14 +++++++-------
 tests/test-layers-filter.c |  8 +++-----
 2 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/docs/nbdkit-filter.pod b/docs/nbdkit-filter.pod
index 98a08ca4..65e56fe5 100644
--- a/docs/nbdkit-filter.pod
+++ b/docs/nbdkit-filter.pod
@@ -133,15 +133,15 @@ C<nbdkit_next_list_exports>, C<nbdkit_next_default_export>,
 C<nbdkit_next_open>) and a structure called C<struct nbdkit_next_ops>.
 These abstract the next plugin or filter in the chain.  There is also
 an opaque pointer C<nxdata> which must be passed along when calling
-these functions.  The value of C<nxdata> passed to C<.open> has a
-stable lifetime that lasts to the corresponding C<.close>, with all
+these functions.  The value of C<nxdata> passed to C<.prepare> has a
+stable lifetime that lasts to the corresponding C<.finalize>, with all
 intermediate functions (such as C<.pread>) receiving the same value
 for convenience.  Functions where C<nxdata> is not reused are
 C<.config>, C<.config_complete>, C<.get_ready>, and C<.after_fork>,
 which are called during initialization outside any connections, and
-C<.preconnect>, C<.list_exports>, and C<.default_export>, which are
-called based on client connections but prior to the stable lifetime of
-C<.open>.
+C<.preconnect>, C<.list_exports>, C<.default_export>, and C<.open>
+which are called based on client connections but prior to the stable
+lifetime of C<.prepare>.

 =head2 Next config, open and close

@@ -865,7 +865,7 @@ extents covering the region C<[offset..offset+count-1]>.

  struct nbdkit_extents *nbdkit_extents_full (
                              struct nbdkit_next_ops *next_ops,
-                             nbdkit_backend *nxdata,
+                             void *nxdata,
                              uint32_t count, uint64_t offset,
                              uint32_t flags, int *err);

@@ -885,7 +885,7 @@ A convenience function is provided to filters only which makes it
 easier to ensure that the client only encounters aligned extents.

  int nbdkit_extents_aligned (struct nbdkit_next_ops *next_ops,
-                             nbdkit_backend *nxdata,
+                             void *nxdata,
                              uint32_t count, uint64_t offset,
                              uint32_t flags, uint32_t align,
                              struct nbdkit_extents *extents, int *err);
diff --git a/tests/test-layers-filter.c b/tests/test-layers-filter.c
index fcd13830..fc2fcbfd 100644
--- a/tests/test-layers-filter.c
+++ b/tests/test-layers-filter.c
@@ -1,5 +1,5 @@
 /* nbdkit
- * Copyright (C) 2018-2020 Red Hat Inc.
+ * Copyright (C) 2018-2021 Red Hat Inc.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
@@ -132,14 +132,12 @@ static void *
 test_layers_filter_open (nbdkit_next_open *next, void *nxdata,
                          int readonly, const char *exportname, int is_tls)
 {
-  struct handle *h = malloc (sizeof *h);
+  struct handle *h = calloc (1, sizeof *h);

   if (!h) {
     perror ("malloc");
     exit (1);
   }
-  h->nxdata = nxdata;
-  h->next_ops = NULL;

   if (next (nxdata, readonly, exportname) == -1)
     return NULL;
@@ -164,8 +162,8 @@ test_layers_filter_prepare (struct nbdkit_next_ops *next_ops, void *nxdata,
   struct handle *h = handle;

   assert (h->next_ops == NULL);
-  assert (h->nxdata == nxdata);
   h->next_ops = next_ops;
+  h->nxdata = nxdata;
   DEBUG_FUNCTION;
   return 0;
 }
-- 
2.30.1