sys: Add Disjoint-set data structure

Add a set of Disjoint-set functions (`find`, `union`)
to handle queries between sets.

Signed-off-by: James Roy <[email protected]>

Author: rruuaanng

doc/releases/release-notes-4.3.rst

@@ -65,6 +65,14 @@ New APIs and options
 
 .. zephyr-keep-sorted-start re(^\* \w)
 
+
+* Utilities
+
+  * :c:struct:`sys_set_node`
+  * :c:func:`sys_set_makeset`
+  * :c:func:`sys_set_find`
+  * :c:func:`sys_set_union`
+
 .. zephyr-keep-sorted-stop
 
 New Boards

include/zephyr/sys/set.h

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) 2025 James Roy <[email protected]>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file
+ * @defgroup union_find_apis Disjoint-set
+ * @ingroup datastructure_apis
+ *
+ * @brief Disjoint-set implementation
+ *
+ * This implements a disjoint-set (union-find) that guarantees
+ * O(alpha(n)) runtime for all operations. The algorithms and
+ * naming are conventional per existing academic and didactic
+ * implementations, c.f.:
+ *
+ * https://en.wikipedia.org/wiki/Disjoint-set_data_structure
+ *
+ * @{
+ */
+
+#ifndef ZEPHYR_INCLUDE_SYS_SET_H_
+#define ZEPHYR_INCLUDE_SYS_SET_H_
+
+#include <stdint.h>
+
+/**
+ * @brief Disjoint-set node structure
+ */
+struct sys_set_node {
+	/** @cond INTERNAL_HIDDEN */
+	struct sys_set_node *parent;
+	uint16_t rank;
+	/** @endcond */
+};
+
+/**
+ * @brief Initialize a disjoint-set.
+ *
+ * @param node Pointer to a sys_set_node structure.
+ */
+static inline void sys_set_makeset(struct sys_set_node *node)
+{
+	node->parent = node;
+	node->rank = 0;
+}
+
+/**
+ * @brief Find the root of the disjoint-set.
+ *
+ * @param node Pointer to a sys_set_node structure.
+ * @return Pointer to the root sys_set_node of the set containing the @p node.
+ */
+struct sys_set_node *sys_set_find(struct sys_set_node *node);
+
+/**
+ * @brief Merge two nodes into the same disjoint-set.
+ *
+ * This function attaches the node with the smaller rank to the one with the
+ * larger rank. That say, if @p node1 has a smaller rank than @p node2, it will
+ * be linked to @p node2.
+ *
+ * @param node1 Pointer to a sys_set_node structure.
+ * @param node2 Pointer to a sys_set_node structure.
+ */
+void sys_set_union(struct sys_set_node *node1, struct sys_set_node *node2);
+
+/** @} */
+
+#endif /* ZEPHYR_INCLUDE_SYS_SET_H_ */

lib/utils/set.c

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2025 James Roy <[email protected]>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/sys/set.h>
+
+struct sys_set_node *sys_set_find(struct sys_set_node *node)
+{
+	struct sys_set_node *parent;
+
+	while (node != node->parent) {
+		parent = node->parent;
+		node->parent = parent->parent;
+		node = parent;
+	}
+
+	return node;
+}
+
+void sys_set_union(struct sys_set_node *node1, struct sys_set_node *node2)
+{
+	struct sys_set_node *root1 = sys_set_find(node1);
+	struct sys_set_node *root2 = sys_set_find(node2);
+
+	if (root1 == root2) {
+		return;
+	}
+
+	if (root1->rank < root2->rank) {
+		root1->parent = root2;
+	} else if (root1->rank > root2->rank) {
+		root2->parent = root1;
+	} else {
+		root2->parent = root1;
+		root1->rank++;
+	}
+}