Struct TopologyObject

#[repr(C)]
pub struct TopologyObject { /* private fields */ }

Implementations

impl TopologyObject

pub fn object_type(&self) -> ObjectType

The type of the object.

Examples found in repository

examples/processor_cache.rs (line 17)

fn main() {
    let topo = Topology::new();

    let pu = topo.objects_with_type(&ObjectType::PU).unwrap()[0];

    let mut parent = pu.parent();
    let mut levels = 0;
    let mut size = 0;

    while let Some(p) = parent {
        if p.object_type() == ObjectType::Cache {
            levels += 1;
            // This should actually be size(), but there is a (compiler) bug? with the c-ffi unions
            size += p.cache_attributes().unwrap().size;
        }
        parent = p.parent();
    }

    println!("*** Logical processor 0 has {} caches totalling {} KB",
             levels,
             size / 1024);
}

pub fn memory(&self) -> &TopologyObjectMemory

The memory attributes of the object.

pub fn os_index(&self) -> u32

The OS-provided physical index number.

It is not guaranteed unique across the entire machine, except for PUs and NUMA nodes.

Examples found in repository

examples/walk_tree.rs (line 15)

fn print_children(topo: &Topology, obj: &TopologyObject, depth: usize) {
    let padding = std::iter::repeat(" ").take(depth).collect::<String>();
    println!("{}{}: #{}", padding, obj, obj.os_index());

    for i in 0..obj.arity() {
        print_children(topo, obj.children()[i as usize], depth + 1);
    }
}

pub fn name(&self) -> String

The name of the object, if set.

pub fn depth(&self) -> u32

Vertical index in the hierarchy.

If the topology is symmetric, this is equal to the parent depth plus one, and also equal to the number of parent/child links from the root object to here.

pub fn logical_index(&self) -> u32

Horizontal index in the whole list of similar objects, hence guaranteed unique across the entire machine.

Could be a “cousin_rank” since it’s the rank within the “cousin” list below.

pub fn sibling_rank(&self) -> u32

This objects index in the parents children list.

pub fn arity(&self) -> u32

The number of direct children.

Examples found in repository

examples/walk_tree.rs (line 17)

fn print_children(topo: &Topology, obj: &TopologyObject, depth: usize) {
    let padding = std::iter::repeat(" ").take(depth).collect::<String>();
    println!("{}{}: #{}", padding, obj, obj.os_index());

    for i in 0..obj.arity() {
        print_children(topo, obj.children()[i as usize], depth + 1);
    }
}

pub fn symmetric_subtree(&self) -> bool

Set if the subtree of objects below this object is symmetric, which means all children and their children have identical subtrees.

pub fn children(&self) -> Vec<&TopologyObject>

All direct children of this object.

Examples found in repository

examples/walk_tree.rs (line 18)

fn print_children(topo: &Topology, obj: &TopologyObject, depth: usize) {
    let padding = std::iter::repeat(" ").take(depth).collect::<String>();
    println!("{}{}: #{}", padding, obj, obj.os_index());

    for i in 0..obj.arity() {
        print_children(topo, obj.children()[i as usize], depth + 1);
    }
}

pub fn next_cousin(&self) -> Option<&TopologyObject>

Next object of same type and depth.

pub fn prev_cousin(&self) -> Option<&TopologyObject>

Previous object of same type and depth.

pub fn first_child(&self) -> Option<&TopologyObject>

First child of the next depth.

pub fn last_child(&self) -> Option<&TopologyObject>

Last child of the next depth.

pub fn parent(&self) -> Option<&TopologyObject>

Last child of the next depth.

Examples found in repository

examples/processor_cache.rs (line 12)

fn main() {
    let topo = Topology::new();

    let pu = topo.objects_with_type(&ObjectType::PU).unwrap()[0];

    let mut parent = pu.parent();
    let mut levels = 0;
    let mut size = 0;

    while let Some(p) = parent {
        if p.object_type() == ObjectType::Cache {
            levels += 1;
            // This should actually be size(), but there is a (compiler) bug? with the c-ffi unions
            size += p.cache_attributes().unwrap().size;
        }
        parent = p.parent();
    }

    println!("*** Logical processor 0 has {} caches totalling {} KB",
             levels,
             size / 1024);
}

pub fn prev_sibling(&self) -> Option<&TopologyObject>

Previous object below the same parent.

pub fn next_sibling(&self) -> Option<&TopologyObject>

Next object below the same parent.

pub fn cpuset(&self) -> Option<CpuSet>

CPUs covered by this object.

This is the set of CPUs for which there are PU objects in the topology under this object, i.e. which are known to be physically contained in this object and known how (the children path between this object and the PU objects).

Examples found in repository

examples/bind_threads.rs (line 76)

fn cpuset_for_core(topology: &Topology, idx: usize) -> CpuSet {
    let cores = (*topology).objects_with_type(&ObjectType::Core).unwrap();
    match cores.get(idx) {
        Some(val) => val.cpuset().unwrap(),
        None => panic!("No Core found with id {}", idx),
    }
}

examples/bind_to_last_core.rs (line 23)

fn main() {
    let mut topo = Topology::new();

    // Grab last core and exctract its CpuSet
    let mut cpuset = last_core(&mut topo).cpuset().unwrap();

    //  Get only one logical processor (in case the core is SMT/hyper-threaded).
    cpuset.singlify();

    // Print the current cpu binding before explicit setting
    println!("Cpu Binding before explicit bind: {:?}",
             topo.get_cpubind(CPUBIND_PROCESS));
    println!("Cpu Location before explicit bind: {:?}",
             topo.get_cpu_location(CPUBIND_PROCESS));

    // Try to bind all threads of the current (possibly multithreaded) process.
    match topo.set_cpubind(cpuset, CPUBIND_PROCESS) {
        Ok(_) => println!("Correctly bound to last core"),
        Err(e) => println!("Failed to bind: {:?}", e),
    }

    // Print the current cpu binding after explicit setting
    println!("Cpu Binding after explicit bind: {:?}",
             topo.get_cpubind(CPUBIND_PROCESS));
    println!("Cpu Location after explicit bind: {:?}",
             topo.get_cpu_location(CPUBIND_PROCESS));
}

examples/bind_process.rs (line 21)

fn main() {
    let mut topo = Topology::new();

    // load the current pid through libc
    let pid = get_pid();

    println!("Binding Process with PID {:?}", pid);

    // Grab last core and exctract its CpuSet
    let mut cpuset = last_core(&mut topo).cpuset().unwrap();

    // Get only one logical processor (in case the core is SMT/hyper-threaded).
    cpuset.singlify();

    println!("Before Bind: {:?}",
             topo.get_cpubind_for_process(pid, CPUBIND_PROCESS)
                 .unwrap());

    // Last CPU Location for this PID (not implemented on all systems)
    if let Some(l) = topo.get_cpu_location_for_process(pid, CPUBIND_PROCESS) {
        println!("Last Known CPU Location: {:?}", l);
    }

    // Bind to one core.
    topo.set_cpubind_for_process(pid, cpuset, CPUBIND_PROCESS)
        .unwrap();

    println!("After Bind: {:?}",
             topo.get_cpubind_for_process(pid, CPUBIND_PROCESS)
                 .unwrap());

    // Last CPU Location for this PID (not implemented on all systems)
    if let Some(l) = topo.get_cpu_location_for_process(pid, CPUBIND_PROCESS) {
        println!("Last Known CPU Location: {:?}", l);
    }
}

pub fn complete_cpuset(&self) -> Option<CpuSet>

The complete CPU set of logical processors of this object.

This includes not only the same as the cpuset field, but also the CPUs for which topology information is unknown or incomplete, and the CPUs that are ignored when the HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM flag is not set. Thus no corresponding PU object may be found in the topology, because the precise position is undefined. It is however known that it would be somewhere under this object.

pub fn online_cpuset(&self) -> Option<CpuSet>

The CPU set of online logical processors.

This includes the CPUs contained in this object that are online, i.e. draw power and can execute threads. It may however not be allowed to bind to them due to administration rules, see allowed_cpuset.

pub fn allowed_cpuset(&self) -> Option<CpuSet>

The CPU set of allowed logical processors.

This includes the CPUs contained in this object which are allowed for binding, i.e. passing them to the hwloc binding functions should not return permission errors. This is usually restricted by administration rules. Some of them may however be offline so binding to them may still not be possible, see online_cpuset.

pub fn nodeset(&self) -> Option<NodeSet>

NUMA nodes covered by this object or containing this object.

This is the set of NUMA nodes for which there are NODE objects in the topology under or containing it and known how (the children path between this object and the NODE objects).

In the end, these nodes are those that are close to the current object. If the HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM configuration flag is set, some of these nodes may not be allowed for allocation, see allowed_nodeset.

If there are no NUMA nodes in the machine, all the memory is close to this object, so the nodeset is full.

pub fn complete_nodeset(&self) -> Option<NodeSet>

The complete NUMA node set of this object,.

This includes not only the same as the nodeset field, but also the NUMA nodes for which topology information is unknown or incomplete, and the nodes that are ignored when the HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM flag is not set. Thus no corresponding NODE object may be found in the topology, because the precise position is undefined. It is however known that it would be somewhere under this object.

If there are no NUMA nodes in the machine, all the memory is close to this object, so complete_nodeset is full.

pub fn allowed_nodeset(&self) -> Option<NodeSet>

The set of allowed NUMA memory nodes.

This includes the NUMA memory nodes contained in this object which are allowed for memory allocation, i.e. passing them to NUMA node-directed memory allocation should not return permission errors. This is usually restricted by administration rules.

If there are no NUMA nodes in the machine, all the memory is close to this object, so allowed_nodeset is full.

pub fn cache_attributes(&self) -> Option<&TopologyObjectCacheAttributes>

Examples found in repository

examples/processor_cache.rs (line 20)

fn main() {
    let topo = Topology::new();

    let pu = topo.objects_with_type(&ObjectType::PU).unwrap()[0];

    let mut parent = pu.parent();
    let mut levels = 0;
    let mut size = 0;

    while let Some(p) = parent {
        if p.object_type() == ObjectType::Cache {
            levels += 1;
            // This should actually be size(), but there is a (compiler) bug? with the c-ffi unions
            size += p.cache_attributes().unwrap().size;
        }
        parent = p.parent();
    }

    println!("*** Logical processor 0 has {} caches totalling {} KB",
             levels,
             size / 1024);
}

Trait Implementations

impl Display for TopologyObject

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

Formats the value using the given formatter.