Struct hwloc::Topology [] [src]

pub struct Topology {
    // some fields omitted
}

Methods

impl Topology

fn new() -> 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.

fn with_flags(flags: Vec<TopologyFlag>) -> 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::IoDevices]);

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

fn support(&self) -> &TopologySupport

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();
assert_eq!(0, default_topology.flags().len());

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

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();
assert!(topology.depth() > 0);

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

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.

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

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

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

// 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.

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

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.

fn object_at_root(&self) -> &TopologyObject

Returns the TopologyObject at the root of the topology.

Examples

use hwloc::{Topology,TopologyObject};

let topology = Topology::new();

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

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

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

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

Returns all TopologyObjects with the given ObjectType.

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

Returns all TopologyObjects at the given depth.

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

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

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

Get current process or thread binding.

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.

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.

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.

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

Get the current physical binding of thread tid.

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.

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 Send for Topology

impl Sync for Topology

impl Drop for Topology

fn drop(&mut self)