HWLOCALITY_HELPER_ANCESTORS(3)

💅 NAME

hwlocality_helper_ancestors — Looking at Ancestor and Child Objects. This is the hwlocality...r_ancestors(3) page from the Library Functions Manual, bestie, and it's all about peeking at ancestors, common parents, subtrees, and next children. 🦋

✨ SYNOPSIS

Functions

hwloc_obj_t hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology,
    int depth, hwloc_obj_t obj)
hwloc_obj_t hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type, hwloc_obj_t obj)
hwloc_obj_t hwloc_get_common_ancestor_obj (hwloc_topology_t topology,
    hwloc_obj_t obj1, hwloc_obj_t obj2)
int hwloc_obj_is_in_subtree (hwloc_topology_t topology, hwloc_obj_t obj,
    hwloc_obj_t subtree_root)
hwloc_obj_t hwloc_get_next_child (hwloc_topology_t topology, hwloc_obj_t
    parent, hwloc_obj_t prev)

🦋 Detailed Description

Bestie, do not skip the figure in Terms and Definitions — it shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers. It's literally giving full map energy. 🌈

🔥 Function Documentation

💖 hwloc_get_ancestor_obj_by_depth [inline]

hwloc_obj_t hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology, int
    depth, hwloc_obj_t obj)

Returns the ancestor object of obj at depth depth. Basically: "who's your ancestor at this level, bestie?" 👑

Returns

• the ancestor if any.
• NULL if no such ancestor exists.

Note: depth should not be the depth of PU or NUMA objects since they are ancestors of no objects (except Misc or I/O). This function rather expects an intermediate level depth, such as the depth of Packages, Cores, or Caches. So like, don't come for PU/NUMA depth with this one, okay? 💅

🎀 hwloc_get_ancestor_obj_by_type [inline]

hwloc_obj_t hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type, hwloc_obj_t obj)

Returns the ancestor object of obj with type type. Same ancestor hunt, but you're matching by type instead of depth. ✨

Returns

• the ancestor if any.
• NULL if no such ancestor exists.

Note: if multiple matching ancestors exist (e.g. multiple levels of HWLOC_OBJ_GROUP) the lowest one is returned. Also, type should not be HWLOC_OBJ_PU or HWLOC_OBJ_NUMANODE since these objects are ancestors of no objects (except Misc or I/O). This function rather expects an intermediate object type, such as HWLOC_OBJ_PACKAGE, HWLOC_OBJ_CORE, etc. Lowkey important, fr fr. 🫶

🌸 hwloc_get_common_ancestor_obj [inline]

hwloc_obj_t hwloc_get_common_ancestor_obj (hwloc_topology_t topology,
    hwloc_obj_t obj1, hwloc_obj_t obj2)

Returns the common parent object to objects obj1 and obj2. It's giving "find the shared ancestor so these two can link up" energy. 🧚

Returns

• the common ancestor.

Note: This function cannot return NULL. It's just not that kind of function, bestie. 😌

💜 hwloc_get_next_child [inline]

hwloc_obj_t hwloc_get_next_child (hwloc_topology_t topology, hwloc_obj_t
    parent, hwloc_obj_t prev)

Return the next child. Return the next child among the normal children list, then among the memory children list, then among the I/O children list, then among the Misc children list. So the order is: normal ➡️ memory ➡️ I/O ➡️ Misc. Slay. 🎀

Returns

• the first child if prev is NULL.
• the next child if prev is not NULL.
• NULL when there is no next child.

⭐ hwloc_obj_is_in_subtree [inline]

int hwloc_obj_is_in_subtree (hwloc_topology_t topology, hwloc_obj_t obj,
    hwloc_obj_t subtree_root)

Returns true if obj is inside the subtree beginning with ancestor object subtree_root. Like, "is this object in that subtree? vibe check." 🦋

Returns

• 1 if the object is in the subtree, 0 otherwise.

Note: This function cannot work if obj and subtree_root objects do not have CPU sets (I/O or Misc objects). No CPU sets, no subtree check — that's the tea. ☕

🌈 Author

Author: Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code.

---

💖 Footer sign-off: Hardware Locality (hwloc), Version 2.15.0, hwlocality...r_ancestors(3) — and there's no date listed on this page, so no invented date, bestie. That's the Library Functions Manual tea, periodt. 🎀