lib: Discourage usage of deprecated data structures

Put some verbiage in place to warn people that we
are actively discouraging new development that uses
an older data structure.

Signed-off-by: Donald Sharp <sharpd@nvidia.com>

4 files changed, 55 insertions, 0 deletions

diff --git a/lib/hash.h b/lib/hash.h
index 2d00a334be..efa7011bc2 100644
--- a/lib/hash.h
+++ b/lib/hash.h
@@ -13,6 +13,18 @@
 extern "C" {
 #endif
 
+/*
+ * NOTICE:
+ *
+ * If you are reading this file in an effort to add a new hash structure
+ * this is the wrong place to be using it.  Please see the typesafe
+ * data structures, or ask one of the other developers.
+ *
+ * If you are reading this file as a way to update an existing usage
+ * of this data structure, please consider just converting the data
+ * structure to one of the typesafe data structures instead.
+ */
+
 /* Default hash table size.  */
 #define HASH_INITIAL_SIZE 256
 /* Expansion threshold */
diff --git a/lib/linklist.h b/lib/linklist.h
index fd953d0769..f922891df9 100644
--- a/lib/linklist.h
+++ b/lib/linklist.h
@@ -10,6 +10,18 @@
 extern "C" {
 #endif
 
+/*
+ * NOTICE:
+ *
+ * If you are reading this file in an effort to add a new list structure
+ * this is the wrong place to be using it.  Please see the typesafe
+ * data structures, or ask one of the other developers.
+ *
+ * If you are reading this file as a way to update an existing usage
+ * of this data structure, please consider just converting the data
+ * structure to one of the typesafe data structures instead.
+ */
+
 /* listnodes must always contain data to be valid. Adding an empty node
  * to a list is invalid
  */
diff --git a/lib/openbsd-queue.h b/lib/openbsd-queue.h
index df3bbd720f..a2df521f58 100644
--- a/lib/openbsd-queue.h
+++ b/lib/openbsd-queue.h
@@ -17,6 +17,22 @@ extern "C" {
 #endif
 
 /*
+ * NOTICE:
+ *
+ * If you are reading this file in an effort to add a new queue structure
+ * this is the wrong place to be using it.  Please see the typesafe
+ * data structures, or ask one of the other developers.
+ *
+ * If you are reading this file as a way to update an existing usage
+ * of this data structure, please consider just converting the data
+ * structure to one of the typesafe data structures instead.  However,
+ * among converting datastrucutres, the the BSD ones are the lowest
+ * priority / should be converted last. They are already typesafe and
+ * use inline linking nodes, so the only gain is consistency. Please
+ * convert uses of linklist.h and hash.h first.
+ */
+
+/*
  * This file defines five types of data structures: singly-linked lists,
  * lists, simple queues, tail queues and XOR simple queues.
  *
diff --git a/lib/openbsd-tree.h b/lib/openbsd-tree.h
index 4f3985bbca..ecc3a68f15 100644
--- a/lib/openbsd-tree.h
+++ b/lib/openbsd-tree.h
@@ -10,6 +10,21 @@
 #ifdef __cplusplus
 extern "C" {
 #endif
+/*
+ * NOTICE:
+ *
+ * If you are reading this file in an effort to add a new tree structure
+ * this is the wrong place to be using it.  Please see the typesafe
+ * data structures, or ask one of the other developers.
+ *
+ * If you are reading this file as a way to update an existing usage
+ * of this data structure, please consider just converting the data
+ * structure to one of the typesafe data structures instead.  However,
+ * among converting datastrucutres, the the BSD ones are the lowest
+ * priority / should be converted last. They are already typesafe and
+ * use inline linking nodes, so the only gain is consistency. Please
+ * convert uses of linklist.h and hash.h first.
+ */
 
 /*
  * This file defines data structures for different types of trees: