Hardware Locality (hwloc): Looking at Ancestor and Child Objects

Hardware Locality (hwloc) 2.14.0rc1

Functions
Looking at Ancestor and Child Objects

## 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

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

## ◆ hwloc_get_ancestor_obj_by_depth()

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_get_ancestor_obj_by_type()

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_get_common_ancestor_obj()

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_get_next_child()

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.

## ◆ hwloc_obj_is_in_subtree()

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

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