Hardware Locality (hwloc) 2.16.0
hwloc_obj Struct Reference

#include <hwloc.h>

Data Fields

hwloc_obj_type_t type
char * subtype
unsigned os_index
char * name
hwloc_uint64_t total_memory
union hwloc_obj_attr_u * attr
int depth
unsigned logical_index
struct hwloc_obj * next_cousin
struct hwloc_obj * prev_cousin
struct hwloc_obj * parent
unsigned sibling_rank
struct hwloc_obj * next_sibling
struct hwloc_obj * prev_sibling
int symmetric_subtree
hwloc_cpuset_t cpuset
hwloc_cpuset_t complete_cpuset
hwloc_nodeset_t nodeset
hwloc_nodeset_t complete_nodeset
struct hwloc_info_s * infos
unsigned infos_count
void * userdata
hwloc_uint64_t gp_index
List and array of normal children below this object (except Memory, I/O and Misc children).
unsigned arity
struct hwloc_obj ** children
struct hwloc_obj * first_child
struct hwloc_obj * last_child
List of Memory children below this object.
unsigned memory_arity
struct hwloc_obj * memory_first_child
List of I/O children below this object.
unsigned io_arity
struct hwloc_obj * io_first_child
List of Misc children below this object.
unsigned misc_arity
struct hwloc_obj * misc_first_child

Detailed Description

Structure of a topology object.

Applications must not modify any field except hwloc_obj.userdata.

Field Documentation

◆ type

hwloc_obj_type_t hwloc_obj::type

Type of object.

◆ subtype

char* hwloc_obj::subtype

Subtype string to better describe the type field.

◆ os_index

unsigned hwloc_obj::os_index

OS-provided physical index number. It is not guaranteed unique across the entire machine, except for PUs and NUMA nodes. Set to HWLOC_UNKNOWN_INDEX if unknown or irrelevant for this object.

◆ name

char* hwloc_obj::name

Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name string is more useful than numerical indexes.

◆ total_memory

hwloc_uint64_t hwloc_obj::total_memory

Total memory (in bytes) in NUMA nodes below this object.

◆ attr

union hwloc_obj_attr_u* hwloc_obj::attr

Object type-specific Attributes, may be NULL if no attribute value was found.

◆ depth

int hwloc_obj::depth

Vertical index in the hierarchy.

For normal objects, this is the depth of the horizontal level that contains this object and its cousins of the same type. If the topology is symmetric, this is equal to the parent depth plus one, and also equal to the number of parent/child links from the root object to here.

For special objects (NUMA nodes, I/O and Misc) that are not in the main tree, this is a special negative value that corresponds to their dedicated level, see hwloc_get_type_depth() and hwloc_get_type_depth_e. Those special values can be passed to hwloc functions such hwloc_get_nbobjs_by_depth() as usual.

◆ logical_index

unsigned hwloc_obj::logical_index

Horizontal index in the whole list of similar objects, hence guaranteed unique across the entire machine. Could be a "cousin_rank" since it's the rank within the "cousin" list below Note that this index may change when restricting the topology or when inserting a group.

◆ next_cousin

struct hwloc_obj* hwloc_obj::next_cousin

Next object of same type and depth.

◆ prev_cousin

struct hwloc_obj* hwloc_obj::prev_cousin

Previous object of same type and depth.

◆ parent

struct hwloc_obj* hwloc_obj::parent

Parent, NULL if root (Machine object).

◆ sibling_rank

unsigned hwloc_obj::sibling_rank

Index in parent's children[] array. Or the index in parent's Memory, I/O or Misc children list.

◆ next_sibling

struct hwloc_obj* hwloc_obj::next_sibling

Next object below the same parent (inside the same list of children).

◆ prev_sibling

struct hwloc_obj* hwloc_obj::prev_sibling

Previous object below the same parent (inside the same list of children).

◆ arity

unsigned hwloc_obj::arity

Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedicated children list.

◆ children

struct hwloc_obj** hwloc_obj::children

Normal children, children[0 .. arity -1].

◆ first_child

struct hwloc_obj* hwloc_obj::first_child

First normal child.

◆ last_child

struct hwloc_obj* hwloc_obj::last_child

Last normal child.

◆ symmetric_subtree

int hwloc_obj::symmetric_subtree

Set if the subtree of normal objects below this object is symmetric, which means all normal children and their children have identical subtrees.

Memory, I/O and Misc children are ignored.

If set in the topology root object, lstopo may export the topology as a synthetic string.

◆ memory_arity

unsigned hwloc_obj::memory_arity

Number of Memory children. These children are listed in memory_first_child.

◆ memory_first_child

struct hwloc_obj* hwloc_obj::memory_first_child

First Memory child. NUMA nodes and Memory-side caches are listed here (memory_arity and memory_first_child) instead of in the normal children list. See also hwloc_obj_type_is_memory().

A memory hierarchy starts from a normal CPU-side object (e.g. Package) and ends with NUMA nodes as leaves. There might exist some memory-side caches between them in the middle of the memory subtree.

◆ io_arity

unsigned hwloc_obj::io_arity

Number of I/O children. These children are listed in io_first_child.

◆ io_first_child

struct hwloc_obj* hwloc_obj::io_first_child

First I/O child. Bridges, PCI and OS devices are listed here (io_arity and io_first_child) instead of in the normal children list. See also hwloc_obj_type_is_io().

◆ misc_arity

unsigned hwloc_obj::misc_arity

Number of Misc children. These children are listed in misc_first_child.

◆ misc_first_child

struct hwloc_obj* hwloc_obj::misc_first_child

First Misc child. Misc objects are listed here (misc_arity and misc_first_child) instead of in the normal children list.

◆ cpuset

hwloc_cpuset_t hwloc_obj::cpuset

CPUs covered by this object.

This is the set of CPUs for which there are PU objects in the topology under this object, i.e. which are known to be physically contained in this object and known how (the children path between this object and the PU objects).

If the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED configuration flag is set, some of these CPUs may be online but not allowed for binding, see hwloc_topology_get_allowed_cpuset().

Note
All objects have non-NULL CPU and node sets except Misc and I/O objects.
Its value must not be changed, hwloc_bitmap_dup() must be used instead.

◆ complete_cpuset

hwloc_cpuset_t hwloc_obj::complete_cpuset

The complete CPU set of processors of this object,.

This set includes the main cpuset field but may also contain additional CPUs that do not appear as PU objects in the topology, either because they are unusable (offline or disallowed) or because their precise position is undefined (it is only known that they would be somewhere under the current object).

Disallowed CPUs always appear in the complete_cpuset field, while they only appear in the main cpuset field if the flag HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED is set.

See also ::hwlocality_helper_topology_sets for details about complete and allowed CPU sets.

Note
Its value must not be changed, hwloc_bitmap_dup() must be used instead.

◆ nodeset

hwloc_nodeset_t hwloc_obj::nodeset

NUMA nodes covered by this object or containing this object.

This is the set of memory nodes for which there are NUMANode object in the topology under or above this object, i.e. which are known to be physically contained in this object or containing it and known how (the children path between this object and the NUMANode objects).

In the end, these nodes are those that are close to the current object. Function hwloc_get_local_numanode_objs() may be used to list those NUMA nodes more precisely.

If the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED configuration flag is set, some of these nodes may be online but not allowed for allocation, see hwloc_topology_get_allowed_nodeset().

If there are no NUMA nodes in the machine, all the memory is close to this object, so only the first bit may be set in nodeset.

Note
All objects have non-NULL CPU and node sets except Misc and I/O objects.
Its value must not be changed, hwloc_bitmap_dup() must be used instead.

◆ complete_nodeset

hwloc_nodeset_t hwloc_obj::complete_nodeset

The complete NUMA node set of this object,.

This set includes the nodeset field but may also contain additional nodes that do not appear as NUMANode objects in the topology, either because they are unusable (offline, memory-less or disallowed) or because they precise position is undefined (it is only known that they would be somewhere under the current object).

Disallowed nodes always appear in the complete_nodeset field, while they only appear in the main nodeset field if the flag HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED is set.

See also ::hwlocality_helper_topology_sets for details about complete and allowed node sets.

If there are no NUMA nodes in the machine, all the memory is close to this object, so only the first bit is set in complete_nodeset.

Note
Its value must not be changed, hwloc_bitmap_dup() must be used instead.

◆ infos

struct hwloc_info_s* hwloc_obj::infos

Array of info attributes (name and value strings).

◆ infos_count

unsigned hwloc_obj::infos_count

Size of infos array.

◆ userdata

void* hwloc_obj::userdata

Application-given private data pointer, initialized to NULL, use it as you wish. See hwloc_topology_set_userdata_export_callback() in hwloc/export.h if you wish to export this field to XML.

◆ gp_index

hwloc_uint64_t hwloc_obj::gp_index

Global persistent index. Generated by hwloc, unique across the topology (contrary to os_index) and persistent across topology changes (contrary to logical_index). Mostly used internally, but could also be used by application to identify objects.


The documentation for this struct was generated from the following file: