Struct hwlocality::topology::builder::TopologyBuilder
source · pub struct TopologyBuilder(/* private fields */);
Expand description
Mechanism to build a Topology
with custom configuration
Implementations§
source§impl TopologyBuilder
impl TopologyBuilder
§Topology building
sourcepub fn build(self) -> Result<Topology, RawHwlocError>
pub fn build(self) -> Result<Topology, RawHwlocError>
Load the topology with the previously specified parameters
The binding of the current thread or process may temporarily change during this call but it will be restored before it returns.
§Examples
let flags = BuildFlags::INCLUDE_DISALLOWED;
let topology = Topology::builder().with_flags(flags)?.build()?;
assert_eq!(topology.build_flags(), flags);
source§impl TopologyBuilder
impl TopologyBuilder
§Discovery source
If none of the functions below is called, the default is to detect all the objects of the machine that the caller is allowed to access.
This default behavior may also be modified through environment variables if
the application did not modify it already. Setting HWLOC_XMLFILE
in the
environment enforces the discovery from a XML file as if from_xml_file()
had been called. Setting HWLOC_SYNTHETIC
enforces a synthetic topology as
if from_synthetic()
had been called.
Finally, the return value of Topology::is_this_system()
can be enforced
by setting HWLOC_THISSYSTEM
.
sourcepub fn from_pid(self, pid: ProcessId) -> Result<Self, HybridError<FromPIDError>>
pub fn from_pid(self, pid: ProcessId) -> Result<Self, HybridError<FromPIDError>>
Change which process the topology is viewed from
On some systems, processes may have different views of the machine, for instance the set of allowed CPUs. By default, hwloc exposes the view from the current process. Calling this method permits to make it expose the topology of the machine from the point of view of another process.
§Errors
FromPIDError
if the topology cannot be configured from this process.
§Panics
Some operating systems use signed PIDs, and do not support PIDs greater
than i32::MAX
. This method will panic when passed such an obviously
invalid PID on these operating systems.
sourcepub fn from_synthetic(self, description: &str) -> Result<Self, StringInputError>
pub fn from_synthetic(self, description: &str) -> Result<Self, StringInputError>
Read the topology from a synthetic textual description
Instead of being probed from the host system, topology information will be read from the given textual description.
Setting the environment variable HWLOC_SYNTHETIC
may also result in
this behavior.
CPU and memory binding operations will not do anything with this backend.
§Errors
ContainsNul
ifdescription
contains NUL chars.Invalid
ifdescription
failed hwloc-side validation (most likely it is not a valid Synthetic topology description)
sourcepub fn from_xml(self, xml: &str) -> Result<Self, StringInputError>
pub fn from_xml(self, xml: &str) -> Result<Self, StringInputError>
Read the topology from an XML description
Instead of being probed from the host system, topology information will be read from the given XML description.
CPU and memory binding operations will not to anything with this backend,
unless BuildFlags::ASSUME_THIS_SYSTEM
is set to assert that the
loaded XML file truly matches the underlying system.
§Errors
ContainsNul
ifdescription
contains NUL chars.Invalid
ifdescription
failed hwloc-side validation (most likely it is not a valid XML topology description)
sourcepub fn from_xml_file(
self,
path: impl AsRef<Path>,
) -> Result<Self, FileInputError>
pub fn from_xml_file( self, path: impl AsRef<Path>, ) -> Result<Self, FileInputError>
Read the topology from an XML file
This works a lot like TopologyBuilder::from_xml()
, but takes a file
name as a parameter instead of an XML string. The same effect can be
achieved by setting the HWLOC_XMLFILE
environment variable.
The file may have been generated earlier with
Topology::export_xml()
or lstopo file.xml
.
§Errors
BadRustPath(ContainsNul)
ifpath
contains NUL chars.BadRustPath(NotUnicode)
ifpath
is not valid Unicode.Invalid
ifpath
fails hwloc-side validation (most likely the path does not exist, is not accessible for reading, or the file does not context valid XML)
sourcepub fn without_component(
self,
name: &str,
) -> Result<Self, HybridError<NulError>>
Available on crate feature hwloc-2_1_0
only.
pub fn without_component( self, name: &str, ) -> Result<Self, HybridError<NulError>>
hwloc-2_1_0
only.Prevent a discovery component from being used for a topology
name
is the name of the discovery component that should not be used
when loading topology topology. The name is a string such as “cuda”.
For components with multiple phases, it may also be suffixed with the
name of a phase, for instance “linux:io”. A list of components
distributed with hwloc can be found
in the hwloc
documentation.
This may be used to avoid expensive parts of the discovery process. For instance, CUDA-specific discovery may be expensive and unneeded while generic I/O discovery could still be useful.
§Errors
NulError
ifname
contains NUL chars.
source§impl TopologyBuilder
impl TopologyBuilder
§Detection configuration and query
sourcepub fn with_flags(
self,
flags: BuildFlags,
) -> Result<Self, HybridError<FlagsError<BuildFlags>>>
pub fn with_flags( self, flags: BuildFlags, ) -> Result<Self, HybridError<FlagsError<BuildFlags>>>
Set topology building flags
If this function is called multiple times, the last invocation will erase and replace the set of flags that was previously set.
§Errors
Rust(FlagsError)
ifflags
were found to be invalid on the Rust side. You may want to cross-check the documentation ofBuildFlags
for more information about which combinations of flags are considered valid.
§Examples
let topology = Topology::builder()
.with_flags(BuildFlags::ASSUME_THIS_SYSTEM)?
.build()?;
sourcepub fn flags(&self) -> BuildFlags
pub fn flags(&self) -> BuildFlags
Check current topology building flags (empty by default)
sourcepub fn with_type_filter(
self,
ty: ObjectType,
filter: TypeFilter,
) -> Result<Self, HybridError<TypeFilterError>>
pub fn with_type_filter( self, ty: ObjectType, filter: TypeFilter, ) -> Result<Self, HybridError<TypeFilterError>>
Set the filtering for the given object type
§Errors
CantKeepGroup
if one attempts to setTypeFilter::KeepAll
forGroup
objects, which is not allowed by hwloc.CantIgnore
if one attempts to ignore the top- and bottom-levelMachine
,PU
andNUMANode
types.StructureIrrelevant
if one attempts to setTypeFilter::KeepStructure
for I/O andMisc
objects, for which topology structure does not matter.
sourcepub fn with_common_type_filter(
self,
filter: TypeFilter,
) -> Result<Self, RawHwlocError>
pub fn with_common_type_filter( self, filter: TypeFilter, ) -> Result<Self, RawHwlocError>
Set the filtering for all object types
If some types do not support this filtering, they are silently ignored.
sourcepub fn with_cpu_cache_type_filter(
self,
filter: TypeFilter,
) -> Result<Self, RawHwlocError>
pub fn with_cpu_cache_type_filter( self, filter: TypeFilter, ) -> Result<Self, RawHwlocError>
Set the filtering for all CPU cache object types
Memory-side caches are not involved since they are not CPU caches.
sourcepub fn with_cpu_icache_type_filter(
self,
filter: TypeFilter,
) -> Result<Self, RawHwlocError>
pub fn with_cpu_icache_type_filter( self, filter: TypeFilter, ) -> Result<Self, RawHwlocError>
Set the filtering for all CPU instruction cache object types
Memory-side caches are not involved since they are not CPU caches.
sourcepub fn with_io_type_filter(
self,
filter: TypeFilter,
) -> Result<Self, HybridError<TypeFilterError>>
pub fn with_io_type_filter( self, filter: TypeFilter, ) -> Result<Self, HybridError<TypeFilterError>>
Set the filtering for all I/O object types
§Errors
StructureIrrelevant
if one attempts to setTypeFilter::KeepStructure
, as topology structure does not matter for I/O objects.
sourcepub fn type_filter(&self, ty: ObjectType) -> Result<TypeFilter, RawHwlocError>
pub fn type_filter(&self, ty: ObjectType) -> Result<TypeFilter, RawHwlocError>
Current filtering for the given object type