Libguestfs - Jan 2019 - [PATCH nbdkit] plugins, filters: Define and use NBDKIT_HANDLE_NOT_NEEDED.

A common idiom where we don't need a per-connection handle is:

  static void *
  myplugin_open (int readonly)
  {
    static int handle;
    return &handle;
  }

We need to return some non-NULL value, but we don't care what.

This commit defines a macro NBDKIT_HANDLE_NOT_NEEDED which contains a
meaningless non-NULL pointer which can be used instead of the above.
This is more descriptive than the previous code.
---
 docs/nbdkit-filter.pod              | 3 ++-
 docs/nbdkit-plugin.pod              | 3 ++-
 include/nbdkit-common.h             | 5 +++++
 filters/cache/cache.c               | 7 +------
 filters/cow/cow.c                   | 7 +------
 filters/error/error.c               | 4 +---
 plugins/example1/example1.c         | 7 +++----
 plugins/floppy/floppy.c             | 7 +------
 plugins/full/full.c                 | 4 +---
 plugins/iso/iso.c                   | 7 +------
 plugins/memory/memory.c             | 5 +----
 plugins/null/null.c                 | 4 +---
 plugins/partitioning/partitioning.c | 5 +----
 plugins/pattern/pattern.c           | 5 +----
 plugins/random/random.c             | 5 +----
 15 files changed, 23 insertions(+), 55 deletions(-)

diff --git a/docs/nbdkit-filter.pod b/docs/nbdkit-filter.pod
index 77ecd7b..dd5c4ed 100644
--- a/docs/nbdkit-filter.pod
+++ b/docs/nbdkit-filter.pod
@@ -281,7 +281,8 @@ to other filter callbacks and could be freed in the
C<.close>
 callback.
 
 Note that the handle is completely opaque to nbdkit, but it must not
-be NULL.
+be NULL.  If you don't need to use a handle, return
+C<NBDKIT_HANDLE_NOT_NEEDED> which is a meaningless non-NULL pointer.
 
 If there is an error, C<.open> should call C<nbdkit_error> with an
 error message and return C<NULL>.
diff --git a/docs/nbdkit-plugin.pod b/docs/nbdkit-plugin.pod
index 0f8ef79..e909b0d 100644
--- a/docs/nbdkit-plugin.pod
+++ b/docs/nbdkit-plugin.pod
@@ -453,7 +453,8 @@ is passed back to other callbacks and could be freed in the
C<.close>
 callback.
 
 Note that the handle is completely opaque to nbdkit, but it must not
-be NULL.
+be NULL.  If you don't need to use a handle, return
+C<NBDKIT_HANDLE_NOT_NEEDED> which is a meaningless non-NULL pointer.
 
 The C<readonly> flag informs the plugin that the user requested a
 read-only connection using the I<-r> flag on the command line.  Note
diff --git a/include/nbdkit-common.h b/include/nbdkit-common.h
index 9295b8a..bc3c438 100644
--- a/include/nbdkit-common.h
+++ b/include/nbdkit-common.h
@@ -70,6 +70,11 @@ extern int nbdkit_parse_bool (const char *str);
 extern int nbdkit_read_password (const char *value, char **password);
 extern char *nbdkit_realpath (const char *path);
 
+/* A meaningless non-NULL pointer which can be used when you don't
+ * need a per-connection handle.
+ */
+#define NBDKIT_HANDLE_NOT_NEEDED ((void *) &nbdkit_error)
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/filters/cache/cache.c b/filters/cache/cache.c
index 67dde23..dc7ceab 100644
--- a/filters/cache/cache.c
+++ b/filters/cache/cache.c
@@ -177,15 +177,10 @@ cache_config_complete (nbdkit_next_config_complete *next,
void *nxdata)
 static void *
 cache_open (nbdkit_next_open *next, void *nxdata, int readonly)
 {
-  /* We don't use the handle, so this just provides a non-NULL
-   * pointer that we can return.
-   */
-  static int handle;
-
   if (next (nxdata, readonly) == -1)
     return NULL;
 
-  return &handle;
+  return NBDKIT_HANDLE_NOT_NEEDED;
 }
 
 /* Get the file size and ensure the cache is the correct size. */
diff --git a/filters/cow/cow.c b/filters/cow/cow.c
index fe5b00e..b8f08c4 100644
--- a/filters/cow/cow.c
+++ b/filters/cow/cow.c
@@ -70,16 +70,11 @@ cow_unload (void)
 static void *
 cow_open (nbdkit_next_open *next, void *nxdata, int readonly)
 {
-  /* We don't use the handle, so this just provides a non-NULL
-   * pointer that we can return.
-   */
-  static int handle;
-
   /* Always pass readonly=1 to the underlying plugin. */
   if (next (nxdata, 1) == -1)
     return NULL;
 
-  return &handle;
+  return NBDKIT_HANDLE_NOT_NEEDED;
 }
 
 /* Get the file size and ensure the overlay is the correct size. */
diff --git a/filters/error/error.c b/filters/error/error.c
index c897c76..598bd1f 100644
--- a/filters/error/error.c
+++ b/filters/error/error.c
@@ -240,12 +240,10 @@ error_config (nbdkit_next_config *next, void *nxdata,
 static void *
 error_open (nbdkit_next_open *next, void *nxdata, int readonly)
 {
-  static int handle;
-
   if (next (nxdata, readonly) == -1)
     return NULL;
 
-  return &handle;
+  return NBDKIT_HANDLE_NOT_NEEDED;
 }
 
 /* This function injects a random error. */
diff --git a/plugins/example1/example1.c b/plugins/example1/example1.c
index 871efb7..ddafc60 100644
--- a/plugins/example1/example1.c
+++ b/plugins/example1/example1.c
@@ -131,11 +131,10 @@ static void *
 example1_open (int readonly)
 {
   /* In this trivial example we don't care about per-connection
-   * handles (every connection serves up the same content and there is
-   * no connection state), so we just have to return something that is
-   * non-NULL and doesn't need to be freed.
+   * handles because every connection serves up the same content and
+   * there is no connection state.
    */
-  return data;
+  return NBDKIT_HANDLE_NOT_NEEDED;
 }
 
 /* Size of the data we are going to serve. */
diff --git a/plugins/floppy/floppy.c b/plugins/floppy/floppy.c
index 769448c..5e23c88 100644
--- a/plugins/floppy/floppy.c
+++ b/plugins/floppy/floppy.c
@@ -110,12 +110,7 @@ floppy_config_complete (void)
 static void *
 floppy_open (int readonly)
 {
-  /* We don't need a per-connection handle, so this just acts as a
-   * pointer to return.
-   */
-  static int h;
-
-  return &h;
+  return NBDKIT_HANDLE_NOT_NEEDED;
 }
 
 #define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL
diff --git a/plugins/full/full.c b/plugins/full/full.c
index 3f5159f..cb18a48 100644
--- a/plugins/full/full.c
+++ b/plugins/full/full.c
@@ -83,9 +83,7 @@ full_config_complete (void)
 static void *
 full_open (int readonly)
 {
-  static int handle;
-
-  return &handle;
+  return NBDKIT_HANDLE_NOT_NEEDED;
 }
 
 #define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL
diff --git a/plugins/iso/iso.c b/plugins/iso/iso.c
index bed8486..7ed5e7a 100644
--- a/plugins/iso/iso.c
+++ b/plugins/iso/iso.c
@@ -239,12 +239,7 @@ iso_config_complete (void)
 static void *
 iso_open (int readonly)
 {
-  /* We don't need a per-connection handle, so this just acts as a
-   * pointer to return.
-   */
-  static int h;
-
-  return &h;
+  return NBDKIT_HANDLE_NOT_NEEDED;
 }
 
 #define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL
diff --git a/plugins/memory/memory.c b/plugins/memory/memory.c
index 8e5c084..4013087 100644
--- a/plugins/memory/memory.c
+++ b/plugins/memory/memory.c
@@ -103,10 +103,7 @@ memory_config_complete (void)
 static void *
 memory_open (int readonly)
 {
-  /* Used only as a handle pointer. */
-  static int mh;
-
-  return &mh;
+  return NBDKIT_HANDLE_NOT_NEEDED;
 }
 
 #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
diff --git a/plugins/null/null.c b/plugins/null/null.c
index cee22f5..20d333e 100644
--- a/plugins/null/null.c
+++ b/plugins/null/null.c
@@ -72,9 +72,7 @@ null_config (const char *key, const char *value)
 static void *
 null_open (int readonly)
 {
-  static int handle;
-
-  return &handle;
+  return NBDKIT_HANDLE_NOT_NEEDED;
 }
 
 #define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL
diff --git a/plugins/partitioning/partitioning.c
b/plugins/partitioning/partitioning.c
index 2889e67..43bdd7c 100644
--- a/plugins/partitioning/partitioning.c
+++ b/plugins/partitioning/partitioning.c
@@ -276,10 +276,7 @@ partitioning_config_complete (void)
 static void *
 partitioning_open (int readonly)
 {
-  /* We don't need a handle.  This is a non-NULL pointer we can return. */
-  static int h;
-
-  return &h;
+  return NBDKIT_HANDLE_NOT_NEEDED;
 }
 
 #define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL
diff --git a/plugins/pattern/pattern.c b/plugins/pattern/pattern.c
index 46b5abd..1d1b234 100644
--- a/plugins/pattern/pattern.c
+++ b/plugins/pattern/pattern.c
@@ -73,14 +73,11 @@ pattern_config (const char *key, const char *value)
 
 #define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL
 
-/* No meaning, just used as the address for the handle. */
-static int ph;
-
 /* Create the per-connection handle. */
 static void *
 pattern_open (int readonly)
 {
-  return &ph;
+  return NBDKIT_HANDLE_NOT_NEEDED;
 }
 
 /* Get the disk size. */
diff --git a/plugins/random/random.c b/plugins/random/random.c
index 72caaed..9c805ab 100644
--- a/plugins/random/random.c
+++ b/plugins/random/random.c
@@ -93,14 +93,11 @@ random_config (const char *key, const char *value)
 
 #define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL
 
-/* No meaning, just used as the address for the handle. */
-static int rndh;
-
 /* Create the per-connection handle. */
 static void *
 random_open (int readonly)
 {
-  return &rndh;
+  return NBDKIT_HANDLE_NOT_NEEDED;
 }
 
 /* Get the disk size. */
-- 
2.19.2