# 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 `TopologyObject`

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