store, plugin: Let the plugin module determine an objects backends.

[sysdb.git] / src / include / utils / avltree.h

diff --git a/src/include/utils/avltree.h b/src/include/utils/avltree.h
index 548c69506d0215ae8d893ffc18ea7e7646486969..ba495c665ff6e884c2e6d6efdf308b5fc3c1ec79 100644 (file)
--- a/src/include/utils/avltree.h
+++ b/src/include/utils/avltree.h
@@ -30,6 +30,8 @@
 
 #include "core/object.h"
 
+#include <stdbool.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -45,33 +47,102 @@ typedef struct sdb_avltree sdb_avltree_t;
 struct sdb_avltree_iter;
 typedef struct sdb_avltree_iter sdb_avltree_iter_t;
 
+/*
+ * sdb_avltree_create:
+ * Creates an AVL tree. Objects will be compared by their names.
+ */
 sdb_avltree_t *
-sdb_avltree_create(sdb_object_cmp_cb cmp);
+sdb_avltree_create(void);
 
+/*
+ * sdb_avltree_destroy:
+ * Destroy the specified AVL tree and release all included objects (decrement
+ * the ref-count).
+ */
 void
 sdb_avltree_destroy(sdb_avltree_t *tree);
 
+/*
+ * sdb_avltree_clear:
+ * Remove all nodes from the tree, releasing the included objects (decrement
+ * the ref-count).
+ */
 void
 sdb_avltree_clear(sdb_avltree_t *tree);
 
+/*
+ * sdb_avltree_insert:
+ * Insert a new node into the tree. Each object must be unique. This operation
+ * may change the structure of the tree by rebalancing subtrees which no
+ * longer comply with the rules of AVL.
+ *
+ * Returns:
+ *  - 0 on success
+ *  - a negative value else
+ */
 int
 sdb_avltree_insert(sdb_avltree_t *tree, sdb_object_t *obj);
 
+/*
+ * sdb_avltree_lookup:
+ * Lookup an object from a tree by name.
+ *
+ * Returns:
+ *  - the requested object
+ *  - NULL if no such object exists
+ */
+sdb_object_t *
+sdb_avltree_lookup(sdb_avltree_t *tree, const char *name);
+
+/*
+ * sdb_avltree_get_iter, sdb_avltree_iter_has_next, sdb_avltree_iter_get_next,
+ * sdb_avltree_iter_destroy:
+ * Iterate through all nodes of the tree. The iterator will start at the
+ * smallest element (based on the name) and then iterate through the sorted
+ * sequence of all nodes.
+ *
+ * sdb_avltree_iter_get_next returns NULL if there is no next element.
+ */
 sdb_avltree_iter_t *
 sdb_avltree_get_iter(sdb_avltree_t *tree);
-
 void
 sdb_avltree_iter_destroy(sdb_avltree_iter_t *iter);
 
-_Bool
+bool
 sdb_avltree_iter_has_next(sdb_avltree_iter_t *iter);
 sdb_object_t *
 sdb_avltree_iter_get_next(sdb_avltree_iter_t *iter);
 
+/*
+ * sdb_avltree_iter_peek_next:
+ * Peek at the next node, if there is one. This is similar to has_next() but
+ * it returns the actual next element without advancing the iterator.
+ *
+ * Returns:
+ *  - the next node, if there is one
+ *  - NULL else
+ */
+sdb_object_t *
+sdb_avltree_iter_peek_next(sdb_avltree_iter_t *iter);
+
+/*
+ * sdb_avltree_size:
+ * Returns the number of nodes in the tree.
+ */
 size_t
 sdb_avltree_size(sdb_avltree_t *tree);
 
-_Bool
+/*
+ * sdb_avltree_valid:
+ * Validate a tree, checking if all rules of AVL are met. All errors will be
+ * reported through the logging sub-system. This function is mainly intended
+ * for debugging and (unit) testing.
+ *
+ * Returns:
+ *  - true if the tree is valid
+ *  - false else
+ */
+bool
 sdb_avltree_valid(sdb_avltree_t *tree);
 
 #ifdef __cplusplus