Struct hwlocality::object::TopologyObject

pub struct TopologyObject(/* private fields */);

Hardware topology object

Like Topology, this is a pretty big struct, so the documentation is sliced into smaller parts:

• Basic identity
• Depth and ancestors
• Cousins and siblings
• Children
• CPU set
• NUMA node set
• Key-value information

You cannot create an owned object of this type, it belongs to the topology.

Implementations

impl TopologyObject

Basic identity

pub fn object_type(&self) -> ObjectType

Type of object

pub fn subtype(&self) -> Option<&CStr>

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.

pub unsafe fn set_subtype_unchecked( &mut self, subtype: &str, ) -> Result<(), NulError>

Available on crate feature hwloc-2_3_0 only.

Set the subtype string

This is something you’ll often want to do when creating Group or Misc objects in order to make them more descriptive.

Safety

This method is only safe to call if you can guarantee that your application links against the same libc/CRT as hwloc.

While linking against a different libc is something that is either outright UB or strongly advised against on every OS, actually following this sanity rule is unfortunately very hard on Windows, where usage of multiple CRTs and pre-built DLLs is the norm, and there is no easy way to tell which CRT version your pre-built hwloc DLL links against to adjust your application build’s CRT choice accordingly.

Which is why hwlocality tries hard to accomodate violations of the rule. And thus the safe version of this method, which assumes that you do follow the rule, is not available on Windows.

Errors

• NulError if subtype contains NUL chars.

pub fn name(&self) -> Option<&CStr>

Object-specific name, if any

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

pub fn attributes(&self) -> Option<ObjectAttributes<'_>>

Object type-specific attributes, if any

pub fn os_index(&self) -> Option<usize>

The OS-provided physical index number

It is not guaranteed unique across the entire machine, except for PUs and NUMA nodes.

Not specified if unknown or irrelevant for this object.

pub fn global_persistent_index(&self) -> TopologyObjectID

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 TopologyObjects originating from a single Topology.

impl TopologyObject

Depth and ancestors

pub fn depth(&self) -> 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 value that is unique to their type.

pub fn parent(&self) -> Option<&Self>

Parent object

Only None for the root Machine object.

pub fn ancestors(&self) -> impl FusedIterator<Item = &Self> + Clone

Chain of parent objects up to the topology root

pub fn ancestor_at_depth<DepthLike>(&self, depth: DepthLike) -> Option<&Self>

where DepthLike: TryInto<Depth>, <DepthLike as TryInto<Depth>>::Error: Debug,

Search for an ancestor at a certain depth

depth can be a Depth, a NormalDepth or an usize.

Will return None if the requested depth is deeper than the depth of the current object.

pub fn first_ancestor_with_type(&self, ty: ObjectType) -> Option<&Self>

Search for the first ancestor with a certain type in ascending order

If multiple matching ancestors exist (which can happen with Group ancestors), the lowest ancestor is returned.

Will return None if the requested type appears deeper than the current object or doesn’t appear in the topology.

pub fn first_common_ancestor(&self, other: &Self) -> Option<&Self>

Search for the first ancestor that is shared with another object

The search will always succeed unless…

• One of self and other is the root Machine object, which has no ancestors.
• self and other do not belong to the same topology, and thus have no shared ancestor.

pub fn is_in_subtree(&self, subtree_root: &Self) -> bool

Truth that this object is in the subtree beginning with ancestor object subtree_root

This will return false if self and subtree_root do not belong to the same topology.

pub fn first_shared_cache(&self) -> Option<&Self>

Get the first data (or unified) CPU cache shared between this object and another object, if any.

Will always return None if called on an I/O or Misc object that does not contain CPUs.

pub fn first_non_io_ancestor(&self) -> Option<&Self>

Get the first non-I/O ancestor object

Find the smallest non-I/O ancestor object. This object (normal or memory) may then be used for binding because it has CPU and node sets and because its locality is the same as this object.

This operation will fail if and only if the object is the root of the topology.

impl TopologyObject

Cousins and siblings

pub fn logical_index(&self) -> usize

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.

pub fn next_cousin(&self) -> Option<&Self>

Next object of same type and depth

pub fn prev_cousin(&self) -> Option<&Self>

Previous object of same type and depth

pub fn sibling_rank(&self) -> usize

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

pub fn next_sibling(&self) -> Option<&Self>

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

pub fn prev_sibling(&self) -> Option<&Self>

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

impl TopologyObject

Children

pub fn normal_arity(&self) -> usize

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

pub fn normal_children( &self, ) -> impl DoubleEndedIterator<Item = &Self> + Clone + ExactSizeIterator + FusedIterator

Normal children of this object

pub fn is_symmetric_subtree(&self) -> bool

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

Memory, I/O and Misc children are ignored when evaluating this property, and it is false for all of these object types.

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

pub fn normal_child_covering_cpuset( &self, set: impl Deref<Target = CpuSet>, ) -> Option<&Self>

Get the child covering at least the given cpuset set

set can be a &'_ CpuSet or a BitmapRef<'_, CpuSet>.

This function will always return None if the given set is empty or this topology object doesn’t have a cpuset (I/O or Misc objects), as no object is considered to cover the empty cpuset.

pub fn memory_arity(&self) -> usize

Number of memory children

pub fn memory_children( &self, ) -> impl ExactSizeIterator<Item = &Self> + Clone + FusedIterator

Memory children of this object

NUMA nodes and Memory-side caches are listed here instead of in the TopologyObject::normal_children() list. See also ObjectType::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.

pub fn total_memory(&self) -> u64

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

Requires DiscoverySupport::numa_memory().

pub fn io_arity(&self) -> usize

Number of I/O children

pub fn io_children( &self, ) -> impl ExactSizeIterator<Item = &Self> + Clone + FusedIterator

I/O children of this object

Bridges, PCI and OS devices are listed here instead of in the TopologyObject::normal_children() list. See also ObjectType::is_io().

pub fn is_bridge_covering_pci_bus(&self, domain: PCIDomain, bus_id: u8) -> bool

Truth that this is a bridge covering the specified PCI bus

pub fn misc_arity(&self) -> usize

Number of Misc children

pub fn misc_children( &self, ) -> impl ExactSizeIterator<Item = &Self> + Clone + FusedIterator

Misc children of this object

Misc objects are listed here instead of in the TopologyObject::normal_children() list.

pub fn all_children(&self) -> impl FusedIterator<Item = &Self> + Clone

Full list of children (normal, then memory, then I/O, then Misc)

impl TopologyObject

CPU set

pub fn cpuset(&self) -> Option<BitmapRef<'_, 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 BuildFlags::INCLUDE_DISALLOWED topology building configuration flag is set, some of these CPUs may be online but not allowed for binding, see Topology::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 unwrap this Option.

Example

println!(
    "Visible CPUs attached to the root object: {:?}",
    topology.root_object().cpuset()
);

pub fn is_inside_cpuset(&self, set: impl Deref<Target = CpuSet>) -> bool

Truth that this object is inside of the given cpuset set

set can be a &'_ CpuSet or a BitmapRef<'_, CpuSet>.

Objects are considered to be inside set if they have a non-empty cpuset which verifies set.includes(object_cpuset).

pub fn covers_cpuset(&self, set: impl Deref<Target = CpuSet>) -> bool

Truth that this object covers the given cpuset set

set can be a &'_ CpuSet or a BitmapRef<'_, CpuSet>.

Objects are considered to cover set if it is non-empty and the object has a cpuset which verifies object_cpuset.includes(set).

pub fn complete_cpuset(&self) -> Option<BitmapRef<'_, CpuSet>>

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 BuildFlags::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.

Example

println!(
    "Overall CPUs attached to the root object: {:?}",
    topology.root_object().complete_cpuset()
);

impl TopologyObject

NUMA node set

pub fn nodeset(&self) -> Option<BitmapRef<'_, NodeSet>>

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+, Topology::local_numa_nodes() may be used to list those NUMA nodes more precisely.

If the BuildFlags::INCLUDE_DISALLOWED topology building configuration flag is set, some of these nodes may not be allowed for allocation, see Topology::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 unwrap this Option.

Example

println!(
    "Visible NUMA nodes attached to the root object: {:?}",
    topology.root_object().nodeset()
);

pub fn complete_nodeset(&self) -> Option<BitmapRef<'_, NodeSet>>

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 BuildFlags::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 the complete nodeset is full.

Example

println!(
    "Overall NUMA nodes attached to the root object: {:?}",
    topology.root_object().complete_nodeset()
);

impl TopologyObject

Key-value information

pub fn infos(&self) -> &[TextualInfo]

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 sane users should not leverage this possibility.

pub fn info(&self, key: &str) -> Option<&CStr>

Search the given key name in object infos and return the corresponding value

Beware that hwloc allows multiple informations with the same key to exist, although no sane programs should leverage this possibility. If multiple keys match the given name, only the first one is returned.

Calling this operation multiple times will result in duplicate work. If you need to do this sort of search many times, consider collecting infos() into a HashMap or BTreeMap for increased lookup efficiency.

pub fn add_info( &mut self, name: &str, value: &str, ) -> Result<(), HybridError<NulError>>

Available on crate feature hwloc-2_3_0 only.

Add the given info name and value pair to the given object

The info is appended to the existing info array even if another key with the same name already exists.

This function may be used to enforce object colors in the lstopo graphical output by using “lstopoStyle” as a name and “Background=#rrggbb” as a value. See CUSTOM COLORS in the lstopo(1) manpage for details.

If value contains some non-printable characters, they will be dropped when exporting to XML.

Errors

• NulError if name or value contains NUL chars.

Trait Implementations

impl Debug for TopologyObject

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

Verbose display of the object’s type and attributes

See the Display implementation if you want a more concise display.

Example

println!("Root object: {:#?}", topology.root_object());

impl Display for TopologyObject

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

Display of the type and attributes that is more concise than Debug

• Shorter type names are used, e.g. “L1Cache” becomes “L1”
• Only the major object attributes are printed

Example

println!("Root object: {}", topology.root_object());

impl<'topology> From<&'topology TopologyObject> for AddDistancesError

Available on crate feature hwloc-2_5_0 only.

fn from(object: &'topology TopologyObject) -> Self

Converts to this type from the input type.

impl<'topology> From<&'topology TopologyObject> for ForeignObjectError

fn from(object: &'topology TopologyObject) -> Self

Converts to this type from the input type.

impl<'topology> From<&'topology TopologyObject> for InitiatorInputError

Available on crate feature hwloc-2_3_0 only.

fn from(object: &'topology TopologyObject) -> Self

Converts to this type from the input type.

impl<'topology> From<&'topology TopologyObject> for InitiatorQueryError

Available on crate feature hwloc-2_3_0 only.

fn from(object: &'topology TopologyObject) -> Self

Converts to this type from the input type.

impl<'topology> From<&'topology TopologyObject> for LocalObjectError

Available on crate feature hwloc-2_5_0 only.

fn from(object: &'topology TopologyObject) -> Self

Converts to this type from the input type.

impl<'target> From<&'target TopologyObject> for MemoryAttributeLocation<'target>

Available on crate feature hwloc-2_3_0 only.

fn from(object: &'target TopologyObject) -> Self

Converts to this type from the input type.

impl<'topology> From<&'topology TopologyObject> for MissingObjCpuSetError

fn from(object: &'topology TopologyObject) -> Self

Converts to this type from the input type.

impl Send for TopologyObject

impl Sync for TopologyObject