Struct hwlocality::object::distance::Distances

pub struct Distances<'topology> { /* private fields */ }

Matrix of distances between a set of objects

This matrix often contains latencies between NUMA nodes (as reported in the System Locality Distance Information Table (SLIT) in the ACPI specification), which may or may not be physically accurate. It corresponds to the latency for accessing the memory of one node from a core in another node. The corresponding kind is DistancesKind::FROM_OS | DistancesKind::FROM_USER. The name of this distances structure is “NUMALatency”.

The names and semantics of other distances matrices currently created by hwloc may be found in the hwloc documentation.

The matrix may also contain bandwidths between random sets of objects, possibly provided by the user, as specified in the kind() attribute.

Resizing a distance matrix is not allowed, however users may freely change their kind and contents.

For instance, on hwloc 2.5+, if there is a single NUMA node per Package, Topology::object_with_same_locality() may be used to convert between them and replace NUMA nodes in the objs array with the corresponding Packages.

See also Distances::transform() for applying some transformations to the structure.

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

Implementations

impl<'topology> Distances<'topology>

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

Available on crate feature hwloc-2_1_0 only.

Description of what a distances structure contains

For instance “NUMALatency” for hardware-provided NUMA distances (ACPI SLIT), or None if unknown.

pub fn kind(&self) -> DistancesKind

Kind of distance matrix

pub fn num_objects(&self) -> usize

Number of objects described by the distance matrix

Safety

Output can be trusted by unsafe code

pub fn objects( &self, ) -> impl DoubleEndedIterator<Item = Option<&TopologyObject>> + Clone + ExactSizeIterator + FusedIterator

Objects described by the distance matrix

These objects are not in any particular order, see methods below for easy ways to find objects and corresponding distance values.

pub fn object_idx(&self, obj: &TopologyObject) -> Option<usize>

Find the row/column index of an object in the distance matrix

This will return None if called with an object that does not belong to the active topology.

Beware that calling this in a loop will result in a lot of duplicate work. It is a good idea to instead build a cache of indices for the objects that you are interested in, or to use the object_distances() iterator if your algorithm allows for it.

pub fn replace_object( &mut self, idx: usize, new_object: Option<&'topology TopologyObject>, ) -> Result<(), ForeignObjectError>

Replace the object at index idx with another

If the new object is unrelated to the original one, you may want to adjust the distance matrix after doing this, which you can using one of the distances_mut(), enumerate_distances_mut() and object_distances_mut() methods.

Errors

ForeignObjectError if new_object does not belong to the same Topology as this distances matrix.

pub fn replace_objects( &mut self, mapping: impl FnMut(usize, Option<&TopologyObject>) -> Option<&'topology TopologyObject>, ) -> Result<(), ForeignObjectError>

Replace all objects using the provided (index, object) -> object mapping

This is more efficient than calling Distances::replace_object() in a loop and allows you to know what object you are replacing.

Errors

ForeignObjectError if any of the TopologyObjects returned by mapping does not belong to the same Topology as this distances matrix.

pub fn distances(&self) -> &[u64]

Distances in sender-major order

This will first report the distance from the first object to the second object, then to the second object, and so on for all other objects. Then the distance from the second object to the first object will be reported, and so on.

The meaning of the distance value depends on Distances::kind().

If you do not know the indices of the objects that you are looking for, you may want to use Distances::object_distances() instead.

pub fn distances_mut(&mut self) -> &mut [u64]

Distances in sender-major order (mutable access)

See also Distances::distances().

pub fn enumerate_distances( &self, ) -> impl DoubleEndedIterator<Item = ((usize, usize), u64)> + Clone + ExactSizeIterator + FusedIterator + '_

Iteration over ((sender index, receiver index), distance) tuples

See also Distances::distances().

pub fn enumerate_distances_mut( &mut self, ) -> impl DoubleEndedIterator<Item = ((usize, usize), &mut u64)> + ExactSizeIterator + FusedIterator

Iteration over ((sender index, receiver index), &mut distance) tuples

See also Distances::distances().

Safety

Output can be trusted by unsafe code

pub fn object_distances( &self, ) -> impl FusedIterator<Item = ((Option<&TopologyObject>, Option<&TopologyObject>), u64)> + Clone

Iteration over ((sender, receiver), distance) tuples

See also Distances::distances().

pub fn object_distances_mut( &mut self, ) -> impl FusedIterator<Item = ((Option<&TopologyObject>, Option<&TopologyObject>), &mut u64)>

Iteration over ((sender, receiver), &mut distance) tuples

See also Distances::distances().

pub fn object_pair_distance( &self, (obj1, obj2): (&TopologyObject, &TopologyObject), ) -> Option<(u64, u64)>

Distance between a pair of objects

Will return the distance from the first to the second input object and the distance from the second to the first input object, if known.

Will return None if one of the objects doesn’t belong to the host topology.

This is a rather expensive operation. If you find yourself needing to do it in a loop, consider rearchitecturing your workflow around object indices or object_distances().

pub fn transform( &mut self, transform: DistancesTransform, ) -> Result<(), HybridError<TransformError>>

Available on crate feature hwloc-2_5_0 only.

Apply a transformation to this distance matrix

This modifies the local copy of the distances structures but does not modify the distances information stored inside the topology (retrieved by another call to Topology::distances() or exported to XML).

To do so, one should add a new distances structure with same name, kind, objects and values (see TopologyEditor::add_distances()) and then remove this old one using one of the TopologyEditor APIs for removing distances.

Objects may also be directly replaced in place using Distances::replace_objects(). One may use e.g. Topology::object_with_same_locality() to easily convert between similar objects of different types.

Errors

TransformError if one attempts to use DistancesTransform::RemoveNone to reduce the number of objects to <2, which is forbidden.

Trait Implementations

impl Debug for Distances<'_>

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

Formats the value using the given formatter.

impl Drop for Distances<'_>

fn drop(&mut self)

Executes the destructor for this type.

impl Index<(usize, usize)> for Distances<'_>

type Output = u64

The returned type after indexing.

fn index(&self, idx: (usize, usize)) -> &u64

Performs the indexing (container[index]) operation.

impl IndexMut<(usize, usize)> for Distances<'_>

fn index_mut(&mut self, idx: (usize, usize)) -> &mut u64

Performs the mutable indexing (container[index]) operation.

impl Send for Distances<'_>

impl Sync for Distances<'_>