Struct hwlocality::memory::attribute::MemoryAttribute
source · pub struct MemoryAttribute<'topology> { /* private fields */ }
hwloc-2_3_0
only.Expand description
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§
source§impl<'topology> MemoryAttribute<'topology>
impl<'topology> MemoryAttribute<'topology>
§Predefined memory attributes
sourcepub const fn capacity(topology: &'topology Topology) -> Self
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()
.
sourcepub const fn locality(topology: &'topology Topology) -> Self
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()
.
sourcepub const fn bandwidth(topology: &'topology Topology) -> Self
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.
sourcepub const fn read_bandwidth(topology: &'topology Topology) -> Self
Available on crate feature hwloc-2_8_0
only.
pub const fn read_bandwidth(topology: &'topology Topology) -> Self
hwloc-2_8_0
only.Read bandwidth in MiB/s, as seen from the given initiator location
sourcepub const fn write_bandwidth(topology: &'topology Topology) -> Self
Available on crate feature hwloc-2_8_0
only.
pub const fn write_bandwidth(topology: &'topology Topology) -> Self
hwloc-2_8_0
only.Write bandwidth in MiB/s, as seen from the given initiator location
sourcepub const fn latency(topology: &'topology Topology) -> Self
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.
sourcepub const fn read_latency(topology: &'topology Topology) -> Self
Available on crate feature hwloc-2_8_0
only.
pub const fn read_latency(topology: &'topology Topology) -> Self
hwloc-2_8_0
only.Read latency in nanoseconds, as seen from the given initiator location
sourcepub const fn write_latency(topology: &'topology Topology) -> Self
Available on crate feature hwloc-2_8_0
only.
pub const fn write_latency(topology: &'topology Topology) -> Self
hwloc-2_8_0
only.Write latency in nanoseconds, as seen from the given initiator location
source§impl<'topology> MemoryAttribute<'topology>
impl<'topology> MemoryAttribute<'topology>
§Memory attribute API
sourcepub fn flags(&self) -> MemoryAttributeFlags
pub fn flags(&self) -> MemoryAttributeFlags
Flags of this memory attribute
sourcepub fn value(
&self,
initiator: Option<MemoryAttributeLocation<'_>>,
target_node: &TopologyObject
) -> Result<u64, HybridError<ValueQueryError>>
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 theinitiator
parameter was set to aTopologyObject
that does not belong to this topologyForeignTarget
if thetarget_node
object does not belong to this topologyNeedInitiator
if noinitiator
was provided but this memory attribute needs oneUnwantedInitiator
if aninitiator
was provided but this memory attribute doesn’t need one
sourcepub fn best_target(
&self,
initiator: Option<MemoryAttributeLocation<'_>>
) -> Result<Option<(&'topology TopologyObject, u64)>, InitiatorInputError>
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 theinitiator
parameter was set to aTopologyObject
that does not belong to this topologyNeedInitiator
if noinitiator
was provided but this memory attribute needs oneUnwantedInitiator
if aninitiator
was provided but this memory attribute doesn’t need one
sourcepub fn best_initiator(
&self,
target: &TopologyObject
) -> Result<Option<(MemoryAttributeLocation<'topology>, u64)>, InitiatorQueryError>
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 initiatorsForeignTarget
iftarget
does not belong to this topology
sourcepub fn targets(
&self,
initiator: Option<MemoryAttributeLocation<'_>>
) -> Result<(Vec<&'topology TopologyObject>, Vec<u64>), HybridError<InitiatorInputError>>
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 theinitiator
parameter was set to aTopologyObject
that does not belong to this topologyNeedInitiator
if noinitiator
was provided but this memory attribute needs oneUnwantedInitiator
if aninitiator
was provided but this memory attribute doesn’t need one
sourcepub fn initiators(
&self,
target_node: &TopologyObject
) -> Result<(Vec<MemoryAttributeLocation<'topology>>, Vec<u64>), HybridError<InitiatorQueryError>>
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 initiatorsForeignTarget
iftarget
does not belong to this topology
Trait Implementations§
source§impl<'topology> Clone for MemoryAttribute<'topology>
impl<'topology> Clone for MemoryAttribute<'topology>
source§fn clone(&self) -> MemoryAttribute<'topology>
fn clone(&self) -> MemoryAttribute<'topology>
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more