hwlocality\_helper\_ancestors(3) Library Functions Manual hwlocality\_helper\_ancestors(3)

# [NAME](#NAME)

hwlocality\_helper\_ancestors - Looking at Ancestor and Child Objects

# [SYNOPSIS](#SYNOPSIS)

## [Functions](#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](#Detailed_Description)

Be sure to see the figure in **Terms and Definitions** that 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.

# [Function Documentation](#Function_Documentation)

## **hwloc\_obj\_t** hwloc\_get\_ancestor\_obj\_by\_depth (**hwloc\_topology\_t** topology, int depth, **hwloc\_obj\_t** obj) \[inline]

Returns the ancestor object of obj at depth depth.

**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.

## **hwloc\_obj\_t** hwloc\_get\_ancestor\_obj\_by\_type (**hwloc\_topology\_t** topology, **hwloc\_obj\_type\_t** type, **hwloc\_obj\_t** obj) \[inline]

Returns the ancestor object of obj with type type.

**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.

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.

## **hwloc\_obj\_t** hwloc\_get\_common\_ancestor\_obj (**hwloc\_topology\_t** topology, **hwloc\_obj\_t** obj1, **hwloc\_obj\_t** obj2) \[inline]

Returns the common parent object to objects obj1 and obj2.

**Returns**

the common ancestor.

**Note**

This function cannot return NULL.

## **hwloc\_obj\_t** hwloc\_get\_next\_child (**hwloc\_topology\_t** topology, **hwloc\_obj\_t** parent, **hwloc\_obj\_t** prev) \[inline]

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.

**Returns**

the first child if prev is NULL.

the next child if prev is not NULL.

NULL when there is no next child.

## [int hwloc\_obj\_is\_in\_subtree (**hwloc\_topology\_t** topology, **hwloc\_obj\_t** obj, **hwloc\_obj\_t** subtree\_root) \[inline\]](#int_hwloc_obj_is_in_subtree_%28)

Returns true if obj is inside the subtree beginning with ancestor object subtree\_root.

**Returns**

1 is 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).

# [Author](#Author)

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

Version 2.15.0 Hardware Locality (hwloc)

---

Document: hwlocality_helper_ancestors(3) from hwloc-cuda-12.8 2.15.0-r0 (Chainguard OS)
Source: https://github.com/open-mpi/hwloc