Skip to content

sys: Add Disjoint-set (union-find) data structure #93300

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

rruuaanng
Copy link
Contributor

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

@rruuaanng rruuaanng changed the title sys: Add Disjoint-set data structure sys: Add Disjoint-set (union-find) data structure Jul 18, 2025
@rruuaanng rruuaanng marked this pull request as ready for review July 18, 2025 06:21
@zephyrbot zephyrbot added area: Utilities area: Base OS Base OS Library (lib/os) labels Jul 18, 2025
Copy link
Member

@henrikbrixandersen henrikbrixandersen left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New features should have test cases added.

#include <stdint.h>

/**
* @brief Disjoint-set node structure
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As this is part of sys directory, what about adding sys prefix to make it clear what the name space is. So I propose that these are called sys_uf_...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or maybe sys_set_*? uf is not very descriptive on its purpose.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that would be even better

Copy link
Contributor Author

@rruuaanng rruuaanng Jul 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I got the idea for the name from this:

/**
* @brief Insert node into tree
*/
void rb_insert(struct rbtree *tree, struct rbnode *node);
/**
* @brief Remove node from tree
*/
void rb_remove(struct rbtree *tree, struct rbnode *node);

Copy link
Member

@dcpleung dcpleung Jul 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIRC, that's before we started adding namespace for various subsys. You can grep and see that most under sys/ has sys_ prefix.

As for naming with set instead of uf, we may add other set operations in the future (e.g. difference and subtraction) so that naming should not be restrictive.

@zephyrbot zephyrbot added the Release Notes To be mentioned in the release notes label Jul 19, 2025
@rruuaanng rruuaanng force-pushed the add-uf branch 2 times, most recently from f37ab3c to 8583e82 Compare July 19, 2025 04:00
Add a set of Disjoint-set functions (`find`, `union`)
to handle queries between sets.

Signed-off-by: James Roy <[email protected]>
Add unit tests for functions (`uf_makeset`, `uf_union` and `uf_find`).

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

Comment on lines +39 to +56
/**
* @brief Initialize a disjoint-set.
*/
static inline void uf_makeset(struct uf_node *node)
{
node->parent = node;
node->rank = 0;
}

/**
* @brief Find the root of the disjoint-set.
*/
struct uf_node *uf_find(struct uf_node *node);

/**
* @brief Merge two nodes into the same disjoint-set.
*/
void uf_union(struct uf_node *node1, struct uf_node *node2);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs full Doxygen comments, including parameters and return values

Comment on lines +72 to +73
* Add a set of Disjoint-set functions (:c:func:`uf_find`, :c:func:`uf_union`) to
handle queries between sets. They are declared in :zephyr_file:`include/zephyr/sys/uf.h`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Add a set of Disjoint-set functions (:c:func:`uf_find`, :c:func:`uf_union`) to
handle queries between sets. They are declared in :zephyr_file:`include/zephyr/sys/uf.h`.
* :c:struct:`uf_node`
* :c:func:`uf_makeset`
* :c:func:`uf_find`
* :c:func:`uf_union`

Copy link
Contributor

@andyross andyross left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Design note on the pointer handling.

Also count me on team sys_set_. "uf" is an expression of deep exasperation.

*/
struct uf_node {
/** @cond INTERNAL_HIDDEN */
struct uf_node *parent;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks suspiciously like an slist, no? Not like linked list handling is that big a deal, but every byte of code savings helps.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area: Base OS Base OS Library (lib/os) area: Utilities Release Notes To be mentioned in the release notes
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants