Struct hwloc_obj

#[repr(C)]
pub struct hwloc_obj {

    pub ty: hwloc_obj_type_t,
    pub subtype: *mut c_char,
    pub os_index: c_uint,
    pub name: *mut c_char,
    pub total_memory: u64,
    pub attr: *mut hwloc_obj_attr_u,
    pub depth: hwloc_get_type_depth_e,
    pub logical_index: c_uint,
    pub next_cousin: hwloc_obj_t,
    pub prev_cousin: hwloc_obj_t,
    pub parent: hwloc_obj_t,
    pub sibling_rank: c_uint,
    pub next_sibling: hwloc_obj_t,
    pub prev_sibling: hwloc_obj_t,
    pub arity: c_uint,
    pub children: *mut hwloc_obj_t,
    pub first_child: hwloc_obj_t,
    pub last_child: hwloc_obj_t,
    pub symmetric_subtree: c_int,
    pub memory_arity: c_uint,
    pub memory_first_child: hwloc_obj_t,
    pub io_arity: c_uint,
    pub io_first_child: hwloc_obj_t,
    pub misc_arity: c_uint,
    pub misc_first_child: hwloc_obj_t,
    pub cpuset: hwloc_cpuset_t,
    pub complete_cpuset: hwloc_cpuset_t,
    pub nodeset: hwloc_nodeset_t,
    pub complete_nodeset: hwloc_nodeset_t,
    pub infos: *mut hwloc_info_s,
    pub infos_count: c_uint,
    pub userdata: *mut c_void,
    pub gp_index: u64,
}

Hardware topology object

This type does not implement Default because hwloc all but guarantees that some inner pointers of this struct will not be null.

Fields

ty: hwloc_obj_type_t

Type of object

subtype: *mut c_char

Subtype string to better describe the type field

See https://hwloc.readthedocs.io/en/v2.9/attributes.html#attributes_normal for a list of subtype strings that hwloc can emit.

os_index: c_uint

The 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: *mut c_char

Object-specific name, if any

Mostly used for identifying OS devices and Misc objects where a name string is more useful than numerical indices.

total_memory: u64

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

May not be accurate if hwloc_topology_discovery_support::numa_memory is not set.

attr: *mut hwloc_obj_attr_u

Object type-specific attributes, if any

depth: hwloc_get_type_depth_e

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 value that is unique to their type.

logical_index: c_uint

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.

Note that this index may change when restricting the topology or when inserting a group.

next_cousin: hwloc_obj_t

Next object of same type and depth

prev_cousin: hwloc_obj_t

Previous object of same type and depth

parent: hwloc_obj_t

Parent object

Only NULL for the root HWLOC_OBJ_MACHINE object.

sibling_rank: c_uint

Index in the parent’s relevant child list for this object type

next_sibling: hwloc_obj_t

Next object below the same parent, in the same child list

prev_sibling: hwloc_obj_t

Previous object below the same parent, in the same child list

arity: c_uint

Number of normal children (excluding Memory, Misc and I/O)

children: *mut hwloc_obj_t

Normal children of this object

first_child: hwloc_obj_t

First normal child of this object

last_child: hwloc_obj_t

Last normal child of this object

symmetric_subtree: c_int

Truth that this object is symmetric, which means all normal children and their children have identical subtrees

Memory, I/O and Misc children are ignored.

If this is true of the root object, then the topology may be exported as a synthetic string.

memory_arity: c_uint

Number of memory children

memory_first_child: hwloc_obj_t

First memory child of this object

NUMA nodes and Memory-side caches are listed here 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. HWLOC_OBJ_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: c_uint

Number of I/O children

io_first_child: hwloc_obj_t

First I/O child of this object

Bridges, PCI and OS devices are listed here instead of in the normal children list. See also hwloc_obj_type_is_io().

misc_arity: c_uint

Number of Misc children

misc_first_child: hwloc_obj_t

First Misc child of this object

Misc objects are listed here instead of in the normal children list.

cpuset: hwloc_cpuset_t

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 topology building configuration flag is set, some of these CPUs may be online but not allowed for binding, see hwloc_topology_get_allowed_cpuset().

All objects have CPU and node sets except Misc and I/O objects, so if you know this object to be a normal or Memory object, you can safely assume this pointer to be non-NULL.

complete_cpuset: hwloc_cpuset_t

The complete CPU set of this object

To the CPUs listed by cpuset, this adds CPUs for which topology information is unknown or incomplete, some offline CPUs, and CPUs that are ignored when the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED topology building configuration flag is not set.

Thus no corresponding PU object may be found in the topology, because the precise position is undefined. It is however known that it would be somewhere under this object.

nodeset: hwloc_nodeset_t

NUMA nodes covered by this object or containing this object.

This is the set of NUMA nodes for which there are NUMA node objects 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 NUMA node objects). In the end, these nodes are those that are close to the current object.

With hwloc 2.3+, hwloc_get_local_numanode_objs() may be used to list those NUMA nodes more precisely.

If the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED topology building configuration flag is set, some of these nodes may not be 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 the nodeset is full.

All objects have CPU and node sets except Misc and I/O objects, so if you know this object to be a normal or Memory object, you can safely assume this pointer to be non-NULL.

complete_nodeset: hwloc_nodeset_t

The complete NUMA node set of this object

To the nodes listed by nodeset, this adds nodes for which topology information is unknown or incomplete, some offline nodes, and nodes that are ignored when the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED topology building configuration flag is not set.

Thus no corresponding NUMANode object may be found in the topology, because the precise position is undefined. It is however known that it would be somewhere under this object.

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

infos: *mut hwloc_info_s

Complete list of (key, value) textual info pairs

hwloc defines a number of standard object info attribute names with associated semantics.

Beware that hwloc allows multiple informations with the same key to exist, although no sane programs should leverage this possibility.

infos_count: c_uint

Number of (key, value) pairs in infos

userdata: *mut c_void

Application-given private data pointer, initialized to NULL, use it as you wish

gp_index: u64

Global persistent index

Generated by hwloc, unique across the topology (contrary to os_index) and persistent across topology changes (contrary to logical_index).

All this means you can safely use this index as a cheap key representing the object in a Set or a Map, as long as that Set or Map only refers to hwloc_objs originating from a single hwloc_topology.

Trait Implementations

impl Clone for hwloc_obj

fn clone(&self) -> hwloc_obj

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for hwloc_obj

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Copy for hwloc_obj