[libvirt] [PATCH v4 02/17] util: Introduce virObjectLookupKeys

[John Ferlan]

Add a new virObjectLockable child virObjectLookupKeys that can be
used by various driver/vir*obj consumers as the means to define the
lookup keys for an object.

The API requires that at least the @key1 argument is provided as
non-NULL thus ensuring that there's at least one key. The keys will
be used as input to a soon to be introduced hash table object that
will support one or two hash tables and manage the various add,
search, and remove functionality using the keys.

The initial consumer will be the driver/vir*obj.c APIs which will
make use of the keys via the @UUID or @Name that is used to uniquely
describe the object.

Signed-off-by: John Ferlan <jferlan at redhat.com>
---
 src/libvirt_private.syms |  2 ++
 src/util/virobject.c     | 88 +++++++++++++++++++++++++++++++++++++++++++++++-
 src/util/virobject.h     | 18 ++++++++++
 3 files changed, 107 insertions(+), 1 deletion(-)

diff --git a/src/libvirt_private.syms b/src/libvirt_private.syms
index 2149b11..082a0ba 100644
--- a/src/libvirt_private.syms
+++ b/src/libvirt_private.syms
@@ -2318,6 +2318,7 @@ virNumaSetupMemoryPolicy;
 # util/virobject.h
 virClassForObject;
 virClassForObjectLockable;
+virClassForObjectLookupKeys;
 virClassForObjectRWLockable;
 virClassIsDerivedFrom;
 virClassName;
@@ -2329,6 +2330,7 @@ virObjectListFree;
 virObjectListFreeCount;
 virObjectLock;
 virObjectLockableNew;
+virObjectLookupKeysNew;
 virObjectNew;
 virObjectRef;
 virObjectRWLockableNew;
diff --git a/src/util/virobject.c b/src/util/virobject.c
index 38db692..aec10eb 100644
--- a/src/util/virobject.c
+++ b/src/util/virobject.c
@@ -68,9 +68,11 @@ struct _virClass {
 static virClassPtr virObjectClass;
 static virClassPtr virObjectLockableClass;
 static virClassPtr virObjectRWLockableClass;
+static virClassPtr virObjectLookupKeysClass;
 
 static void virObjectLockableDispose(void *anyobj);
 static void virObjectRWLockableDispose(void *anyobj);
+static void virObjectLookupKeysDispose(void *anyobj);
 
 static int
 virObjectOnceInit(void)
@@ -93,6 +95,12 @@ virObjectOnceInit(void)
                                                  virObjectRWLockableDispose)))
         return -1;
 
+    if (!(virObjectLookupKeysClass = virClassNew(virObjectLockableClass,
+                                                 "virObjectLookupKeys",
+                                                 sizeof(virObjectLookupKeys),
+                                                 virObjectLookupKeysDispose)))
+        return -1;
+
     return 0;
 }
 
@@ -145,6 +153,21 @@ virClassForObjectRWLockable(void)
 
 
 /**
+ * virClassForObjectLookupKeys:
+ *
+ * Returns the class instance for the virObjectLookupKeys type
+ */
+virClassPtr
+virClassForObjectLookupKeys(void)
+{
+    if (virObjectInitialize() < 0)
+        return NULL;
+
+    return virObjectLookupKeysClass;
+}
+
+
+/**
  * virClassNew:
  * @parent: the parent class
  * @name: the class name
@@ -328,6 +351,68 @@ virObjectRWLockableDispose(void *anyobj)
 
 
 /**
+ * virObjectLookupKeysNew:
+ * @klass: the klass to check
+ * @key1: key to be used for unique identifier (required)
+ * @key2: second key to be used as secondary unique identifier
+ *
+ * Create an object with at least @key1 as a means to provide input
+ * of an input object to add the object into a hash table. If @key2 is
+ * provided, then the object will exist into two hash tables for faster
+ * lookups by key for the table; otherwise, hash table searches would
+ * need to be used to find data from an object that matches some specific
+ * search the caller performs.
+ *
+ * Returns: New object on success, NULL on failure w/ error message set
+ */
+void *
+virObjectLookupKeysNew(virClassPtr klass,
+                       const char *key1,
+                       const char *key2)
+{
+    virObjectLookupKeysPtr obj;
+
+    if (!virClassIsDerivedFrom(klass, virClassForObjectLookupKeys())) {
+        virReportInvalidArg(klass,
+                            _("Class %s must derive from virObjectLookupKeys"),
+                            virClassName(klass));
+        return NULL;
+    }
+
+    if (!key1) {
+        virReportError(VIR_ERR_INVALID_ARG, "%s",
+                       _("key1 must be provided"));
+        return NULL;
+    }
+
+    if (!(obj = virObjectLockableNew(klass)))
+        return NULL;
+
+    if (VIR_STRDUP(obj->key1, key1) < 0)
+        goto error;
+
+    if (VIR_STRDUP(obj->key2, key2) < 0)
+        goto error;
+
+    return obj;
+
+ error:
+    virObjectUnref(obj);
+    return NULL;
+}
+
+
+static void
+virObjectLookupKeysDispose(void *anyobj)
+{
+    virObjectLookupKeysPtr obj = anyobj;
+
+    VIR_FREE(obj->key1);
+    VIR_FREE(obj->key2);
+}
+
+
+/**
  * virObjectUnref:
  * @anyobj: any instance of virObjectPtr
  *
@@ -393,7 +478,8 @@ virObjectRef(void *anyobj)
 static virObjectLockablePtr
 virObjectGetLockableObj(void *anyobj)
 {
-    if (virObjectIsClass(anyobj, virObjectLockableClass))
+    if (virObjectIsClass(anyobj, virObjectLockableClass) ||
+        virObjectIsClass(anyobj, virObjectLookupKeysClass))
         return anyobj;
 
     VIR_OBJECT_USAGE_PRINT_ERROR(anyobj, virObjectLockable);
diff --git a/src/util/virobject.h b/src/util/virobject.h
index ac6cf22..0f7d5ca 100644
--- a/src/util/virobject.h
+++ b/src/util/virobject.h
@@ -37,6 +37,9 @@ typedef virObjectLockable *virObjectLockablePtr;
 typedef struct _virObjectRWLockable virObjectRWLockable;
 typedef virObjectRWLockable *virObjectRWLockablePtr;
 
+typedef struct _virObjectLookupKeys virObjectLookupKeys;
+typedef virObjectLookupKeys *virObjectLookupKeysPtr;
+
 typedef void (*virObjectDisposeCallback)(void *obj);
 
 /* Most code should not play with the contents of this struct; however,
@@ -67,9 +70,18 @@ struct _virObjectRWLockable {
     virRWLock lock;
 };
 
+struct _virObjectLookupKeys {
+    virObjectLockable parent;
+
+    char *key1;
+    char *key2;
+};
+
+
 virClassPtr virClassForObject(void);
 virClassPtr virClassForObjectLockable(void);
 virClassPtr virClassForObjectRWLockable(void);
+virClassPtr virClassForObjectLookupKeys(void);
 
 # ifndef VIR_PARENT_REQUIRED
 #  define VIR_PARENT_REQUIRED ATTRIBUTE_NONNULL(1)
@@ -120,6 +132,12 @@ void *
 virObjectRWLockableNew(virClassPtr klass)
     ATTRIBUTE_NONNULL(1);
 
+void *
+virObjectLookupKeysNew(virClassPtr klass,
+                       const char *key1,
+                       const char *key2)
+    ATTRIBUTE_NONNULL(1);
+
 void
 virObjectLock(void *lockableobj)
     ATTRIBUTE_NONNULL(1);
-- 
2.9.4