Struct hwlocality::memory::attribute::MemoryAttribute

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

Available on crate feature hwloc-2_3_0 only.

Memory attribute

May be either one of the predefined attributes (see associated const fns) or a new attribute created using TopologyEditor::register_memory_attribute().

Implementations

impl<'topology> MemoryAttribute<'topology>

Predefined memory attributes

pub const fn capacity(topology: &'topology Topology) -> Self

Node capacity in bytes (see TopologyObject::total_memory())

This attribute involves no initiator.

Requires DiscoverySupport::numa_memory().

pub const fn locality(topology: &'topology Topology) -> Self

Number of PUs in that locality (i.e. cpuset weight)

Smaller locality is better. This attribute involves no initiator.

Requires DiscoverySupport::pu_count().

pub const fn bandwidth(topology: &'topology Topology) -> Self

Average bandwidth in MiB/s, as seen from the given initiator location

This is the average bandwidth for read and write accesses. If the platform provides individual read and write bandwidths but no explicit average value, hwloc computes and returns the average.

pub const fn read_bandwidth(topology: &'topology Topology) -> Self

Available on crate feature hwloc-2_8_0 only.

Read bandwidth in MiB/s, as seen from the given initiator location

pub const fn write_bandwidth(topology: &'topology Topology) -> Self

Available on crate feature hwloc-2_8_0 only.

Write bandwidth in MiB/s, as seen from the given initiator location

pub const fn latency(topology: &'topology Topology) -> Self

Average latency in nanoseconds, as seen from the given initiator location

This is the average latency for read and write accesses. If the platform value provides individual read and write latencies but no explicit average, hwloc computes and returns the average.

pub const fn read_latency(topology: &'topology Topology) -> Self

Available on crate feature hwloc-2_8_0 only.

Read latency in nanoseconds, as seen from the given initiator location

pub const fn write_latency(topology: &'topology Topology) -> Self

Available on crate feature hwloc-2_8_0 only.

Write latency in nanoseconds, as seen from the given initiator location

impl<'topology> MemoryAttribute<'topology>

Memory attribute API

pub fn name(&self) -> &'topology CStr

Name of this memory attribute

pub fn flags(&self) -> MemoryAttributeFlags

Flags of this memory attribute

pub fn value( &self, initiator: Option<MemoryAttributeLocation<'_>>, target_node: &TopologyObject, ) -> Result<u64, HybridError<ValueQueryError>>

Value of this attribute for a specific initiator and target NUMA node

initiator should be specified if and only if this attribute has the flag MemoryAttributeFlags::NEED_INITIATOR.

The initiator should be a CpuSet when refering to accesses performed by CPU cores. MemoryAttributeLocation::Object is currently unused internally by hwloc, but user-defined memory attributes may for instance use it to provide custom information about host memory accesses performed by GPUs.

Errors

• ForeignInitiator if the initiator parameter was set to a TopologyObject that does not belong to this topology
• ForeignTarget if the target_node object does not belong to this topology
• NeedInitiator if no initiator was provided but this memory attribute needs one
• UnwantedInitiator if an initiator was provided but this memory attribute doesn’t need one

pub fn best_target( &self, initiator: Option<MemoryAttributeLocation<'_>>, ) -> Result<Option<(&'topology TopologyObject, u64)>, InitiatorInputError>

Best target node and associated attribute value, if any, for a given initiator

The notes on initiator semantics in MemoryAttribute::value() also apply to this function.

If multiple targets have the same attribute values, only one is returned (and there is no way to clarify how that one is chosen). Applications that want to detect targets with identical/similar values, or that want to look at values for multiple attributes, should rather get all values using MemoryAttribute::value() and manually select the target they consider the best.

Errors

• ForeignInitiator if the initiator parameter was set to a TopologyObject that does not belong to this topology
• NeedInitiator if no initiator was provided but this memory attribute needs one
• UnwantedInitiator if an initiator was provided but this memory attribute doesn’t need one

pub fn best_initiator( &self, target: &TopologyObject, ) -> Result<Option<(MemoryAttributeLocation<'topology>, u64)>, InitiatorQueryError>

Best initiator and associated attribute value, if any, for a given target node

If multiple initiators have the same attribute values, only one is returned (and there is no way to clarify how that one is chosen). Applications that want to detect initiators with identical/similar values, or that want to look at values for multiple attributes, should rather get all values using MemoryAttribute::value() and manually select the initiator they consider the best.

Errors

• NoInitiators if this memory attribute doesn’t have initiators
• ForeignTarget if target does not belong to this topology

pub fn targets( &self, initiator: Option<MemoryAttributeLocation<'_>>, ) -> Result<(Vec<&'topology TopologyObject>, Vec<u64>), HybridError<InitiatorInputError>>

Target NUMA nodes that have some values for a given attribute, along with the associated values.

An initiator may only be specified if this attribute has the flag MemoryAttributeFlags::NEED_INITIATOR. In that case, it acts as a filter to only report targets that have a value for this initiator.

The initiator should be a CpuSet when refering to accesses performed by CPU cores. MemoryAttributeLocation::Object is currently unused internally by hwloc, but user-defined memory attributes may for instance use it to provide custom information about host memory accesses performed by GPUs.

This function is meant for tools and debugging (listing internal information) rather than for application queries. Applications should rather select useful NUMA nodes with Topology::local_numa_nodes() and then look at their attribute values.

Errors

• ForeignInitiator if the initiator parameter was set to a TopologyObject that does not belong to this topology
• NeedInitiator if no initiator was provided but this memory attribute needs one
• UnwantedInitiator if an initiator was provided but this memory attribute doesn’t need one

pub fn initiators( &self, target_node: &TopologyObject, ) -> Result<(Vec<MemoryAttributeLocation<'topology>>, Vec<u64>), HybridError<InitiatorQueryError>>

Initiators that have values for a given attribute for a specific target NUMA node, along with the associated values

If this memory attribute has no initiator, an empty list is returned.

This function is meant for tools and debugging (listing internal information) rather than for application queries. Applications should rather select useful NUMA nodes with Topology::local_numa_nodes() and then look at their attribute values.

Errors

• NoInitiators if this memory attribute doesn’t have initiators
• ForeignTarget if target does not belong to this topology

Trait Implementations

impl<'topology> Clone for MemoryAttribute<'topology>

fn clone(&self) -> MemoryAttribute<'topology>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for MemoryAttribute<'_>

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

Formats the value using the given formatter.

impl<'topology> Copy for MemoryAttribute<'topology>