Struct hwloc2::Topology

pub struct Topology { /* fields omitted */ }

Implementations

impl Topology

pub fn new() -> Option<Topology>

Creates a new Topology.

If no further customization is needed on init, this method represents the main entry point. A topology is returned which contains the logical representation of the physical hardware.

Examples

use hwloc::Topology;

let topology = Topology::new();

Note that the topology implements the Drop trait, so when it goes out of scope no further cleanup is necessary.

pub fn with_flags(flags: Vec<TopologyFlag>) -> Option<Topology>

Creates a new Topology with custom flags.

This method works like new, but allows to provide a vector of flags which customize the topology discovery process.

Examples

use hwloc::{Topology, TopologyFlag};

let topology = Topology::with_flags(vec![TopologyFlag::IsThisSystem]);

Note that the topology implements the Drop trait, so when it goes out of scope no further cleanup is necessary.

pub fn support(&self) -> &TopologySupport

pub fn flags(&self) -> Vec<TopologyFlag>

Returns the flags currently set for this topology.

Note that the flags are only used during initialization, so this method can just be used for debugging purposes.

Examples

use hwloc::{Topology,TopologyFlag};

let default_topology = Topology::new().unwrap();
assert_eq!(0, default_topology.flags().len());

let topology_with_flags = Topology::with_flags(vec![TopologyFlag::IsThisSystem]).unwrap();
assert_eq!(vec![TopologyFlag::IsThisSystem], topology_with_flags.flags());

pub fn depth(&self) -> u32

Returns the full depth of the topology.

In practice, the full depth of the topology equals the depth of the ObjectType::PU plus one.

The full topology depth is useful to know if one needs to manually traverse the complete topology.

Examples

use hwloc::Topology;

let topology = Topology::new().unwrap();
assert!(topology.depth() > 0);

pub fn depth_for_type(
    &self,
    object_type: &ObjectType
) -> Result<u32, TypeDepthError>

Returns the depth for the given ObjectType.

Examples

use hwloc::{Topology,ObjectType};

let topology = Topology::new().unwrap();

let machine_depth = topology.depth_for_type(&ObjectType::Machine).unwrap();
let pu_depth = topology.depth_for_type(&ObjectType::PU).unwrap();
assert!(machine_depth < pu_depth);

Failures

If hwloc can't find the depth for the given ObjectType, this method will return an error from the TypeDepthError enum. See this one for more info on each specific error.

Note that for ObjectType::Bridge, ObjectType::PCIDevice and ObjectType::OSDevice, always an error will be returned which signals their virtual depth.

pub fn depth_or_below_for_type(
    &self,
    object_type: &ObjectType
) -> Result<u32, TypeDepthError>

pub fn depth_or_above_for_type(
    &self,
    object_type: &ObjectType
) -> Result<u32, TypeDepthError>

pub fn type_at_depth(&self, depth: u32) -> ObjectType

Returns the corresponding ObjectType for the given depth.

Examples

use hwloc::{Topology,ObjectType};

let topology = Topology::new().unwrap();

// Load depth for PU to assert against
let pu_depth = topology.depth_for_type(&ObjectType::PU).unwrap();
// Retrieve the type for the given depth
assert_eq!(ObjectType::PU, topology.type_at_depth(pu_depth));

Panics

This method will panic if the given depth is larger than the full depth minus one. It can't be negative since its an unsigned integer, but be careful with the depth provided in general.

pub fn size_at_depth(&self, depth: u32) -> u32

Returns the number of objects at the given depth.

Examples

use hwloc::Topology;

let topology = Topology::new().unwrap();

let topo_depth = topology.depth();
assert!(topology.size_at_depth(topo_depth - 1) > 0);

Panics

This method will panic if the given depth is larger than the full depth minus one. It can't be negative since its an unsigned integer, but be careful with the depth provided in general.

pub fn object_at_root(&self) -> &TopologyObject

Returns the TopologyObject at the root of the topology.

Examples

use hwloc::{Topology,TopologyObject};

let topology = Topology::new().unwrap();

assert_eq!(topology.type_at_root(), topology.object_at_root().object_type());

pub fn type_at_root(&self) -> ObjectType

Returns the ObjectType at the root of the topology.

This method is a convenient shorthand for type_at_depth(0).

Examples

use hwloc::{Topology,ObjectType};

let topology = Topology::new().unwrap();

let root_type = topology.type_at_root();
let depth_type = topology.type_at_depth(0);
assert_eq!(root_type, depth_type);

pub fn objects_with_type(
    &self,
    object_type: &ObjectType
) -> Result<Vec<&TopologyObject>, TypeDepthError>

Returns all TopologyObjects with the given ObjectType.

pub fn objects_at_depth(&self, depth: u32) -> Vec<&TopologyObject>

Returns all TopologyObjects at the given depth.

pub fn set_cpubind(
    &mut self,
    set: CpuSet,
    flags: CpuBindFlags
) -> Result<(), CpuBindError>

Binds the current process or thread on CPUs given in the CpuSet.

pub fn get_cpubind(&self, flags: CpuBindFlags) -> Option<CpuSet>

Get current process or thread binding.

pub fn set_cpubind_for_process(
    &mut self,
    pid: pid_t,
    set: CpuSet,
    flags: CpuBindFlags
) -> Result<(), CpuBindError>

Binds a process (identified by its pid) on CPUs identified by the given CpuSet.

pub fn get_cpubind_for_process(
    &self,
    pid: pid_t,
    flags: CpuBindFlags
) -> Option<CpuSet>

Get the current physical binding of a process, identified by its pid.

pub fn set_cpubind_for_thread(
    &mut self,
    tid: pthread_t,
    set: CpuSet,
    flags: CpuBindFlags
) -> Result<(), CpuBindError>

Bind a thread (by its tid) on CPUs given in through the CpuSet.

pub fn get_cpubind_for_thread(
    &self,
    tid: pthread_t,
    flags: CpuBindFlags
) -> Option<CpuSet>

Get the current physical binding of thread tid.

pub fn get_cpu_location(&self, flags: CpuBindFlags) -> Option<CpuSet>

Get the last physical CPU where the current process or thread ran.

The operating system may move some tasks from one processor to another at any time according to their binding, so this function may return something that is already outdated.

Flags can include either CPUBIND_PROCESS or CPUBIND_THREAD to specify whether the query should be for the whole process (union of all CPUs on which all threads are running), or only the current thread. If the process is single-threaded, flags can be set to zero to let hwloc use whichever method is available on the underlying OS.

pub fn get_cpu_location_for_process(
    &self,
    pid: pid_t,
    flags: CpuBindFlags
) -> Option<CpuSet>

Get the last physical CPU where a process ran.

The operating system may move some tasks from one processor to another at any time according to their binding, so this function may return something that is already outdated.

Trait Implementations

impl Drop for Topology

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Topology

impl Sync for Topology