Struct hwlocality::topology::builder::TopologyBuilder

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

Mechanism to build a Topology with custom configuration

Implementations

impl TopologyBuilder

Topology building

pub fn new() -> Self

Start building a Topology

Examples

let flags = BuildFlags::INCLUDE_DISALLOWED;
let topology = TopologyBuilder::new().with_flags(flags)?.build()?;
assert_eq!(topology.build_flags(), flags);

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);

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.

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.

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 if description contains NUL chars.
• Invalid if description failed hwloc-side validation (most likely it is not a valid Synthetic topology description)

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 if description contains NUL chars.
• Invalid if description failed hwloc-side validation (most likely it is not a valid XML topology description)

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) if path contains NUL chars.
• BadRustPath(NotUnicode) if path is not valid Unicode.
• Invalid if path fails hwloc-side validation (most likely the path does not exist, is not accessible for reading, or the file does not context valid XML)

pub fn without_component( self, name: &str ) -> Result<Self, HybridError<NulError>>

Available on crate feature 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 if name contains NUL chars.

impl TopologyBuilder

Detection configuration and query

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) if flags were found to be invalid on the Rust side. You may want to cross-check the documentation of BuildFlags for more information about which combinations of flags are considered valid.

Examples

let topology = Topology::builder()
                        .with_flags(BuildFlags::ASSUME_THIS_SYSTEM)?
                        .build()?;

pub fn flags(&self) -> BuildFlags

Check current topology building flags (empty by default)

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 set TypeFilter::KeepAll for Group objects, which is not allowed by hwloc.
• CantIgnore if one attempts to ignore the top- and bottom-level Machine, PU and NUMANode types.
• StructureIrrelevant if one attempts to set TypeFilter::KeepStructure for I/O and Misc objects, for which topology structure does not matter.

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.

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.

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.

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 set TypeFilter::KeepStructure, as topology structure does not matter for I/O objects.

pub fn type_filter(&self, ty: ObjectType) -> Result<TypeFilter, RawHwlocError>

Current filtering for the given object type

Trait Implementations

impl Debug for TopologyBuilder

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

Formats the value using the given formatter.

impl Default for TopologyBuilder

fn default() -> Self

Returns the “default value” for a type.

impl Drop for TopologyBuilder

fn drop(&mut self)

Executes the destructor for this type.

impl Pointer for TopologyBuilder

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

Formats the value using the given formatter.

impl Send for TopologyBuilder

impl Sync for TopologyBuilder