Struct Bitmap

pub struct Bitmap { /* private fields */ }

A generic bitmap, understood by hwloc.

The Bitmap represents a set of objects, typically OS processors – which may actually be hardware threads (represented by CpuSet, which is a type alias for Bitmap – or memory nodes (represented by NodeSet, which is also a typedef for Bitmap).

Both CpuSet and NodeSet are always indexed by OS physical number.

A Bitmap may be of infinite size.

Implementations

impl Bitmap

pub fn new() -> Bitmap

Creates an empty Bitmap.

Examples:

use hwloc::Bitmap;

let bitmap = Bitmap::new();
assert_eq!("", format!("{}", bitmap));
assert_eq!(true, bitmap.is_empty());

pub fn full() -> Bitmap

Creates a full Bitmap.

Examples:

use hwloc::Bitmap;

let bitmap = Bitmap::full();
assert_eq!("0-", format!("{}", bitmap));
assert_eq!(false, bitmap.is_empty());

pub fn from(id: u32) -> Bitmap

Creates a new HwlocBitmap (either CpuSet or NodeSet) and sets one index right away.

Examples:

use hwloc::Bitmap;

let bitmap = Bitmap::from(1);
assert_eq!("1", format!("{}", bitmap));
assert_eq!(false, bitmap.is_empty());

pub fn from_range(begin: u32, end: i32) -> Bitmap

Creates a new Bitmap with the given range.

Examples:

use hwloc::Bitmap;

let bitmap = Bitmap::from_range(0, 5);
assert_eq!("0-5", format!("{}", bitmap));

pub fn from_raw(bitmap: *mut IntHwlocBitmap, manage: bool) -> Bitmap

Wraps the given hwloc bitmap pointer into its Bitmap representation.

This function is not meant to be used directly, it rather serves as the conversion factory when dealing with hwloc-internal structures.

pub fn as_ptr(&self) -> *const IntHwlocBitmap

Returns the containted hwloc bitmap pointer for interaction with hwloc.

pub fn set(&mut self, id: u32)

Set index id in this Bitmap.

Examples:

use hwloc::Bitmap;

let mut bitmap = Bitmap::new();
bitmap.set(4);
assert_eq!("4", format!("{}", bitmap));

pub fn set_range(&mut self, begin: u32, end: i32)

Add indexes from begin to end in this Bitmap.

If end is -1, the range is infinite.

Examples:

use hwloc::Bitmap;

let mut bitmap = Bitmap::new();
bitmap.set_range(3, 5);
assert_eq!("3-5", format!("{}", bitmap));

bitmap.set_range(2, -1);
assert_eq!("2-", format!("{}", bitmap));

pub fn unset(&mut self, id: u32)

Remove index id from the Bitmap.

Examples:

use hwloc::Bitmap;

let mut bitmap = Bitmap::from_range(1,3);
bitmap.unset(1);
assert_eq!("2-3", format!("{}", bitmap));

pub fn unset_range(&mut self, begin: u32, end: i32)

Remove indexes from begin to end in this Bitmap.

If end is -1, the range is infinite.

Examples:

use hwloc::Bitmap;

let mut bitmap = Bitmap::from_range(1,5);
bitmap.unset_range(4,6);
assert_eq!("1-3", format!("{}", bitmap));

bitmap.unset_range(2,-1);
assert_eq!("1", format!("{}", bitmap));

pub fn weight(&self) -> i32

The number of indexes that are in the bitmap.

Examples:

use hwloc::Bitmap;

let mut bitmap = Bitmap::from_range(1,5);
assert_eq!(5, bitmap.weight());
bitmap.unset(3);
assert_eq!(4, bitmap.weight());

pub fn clear(&mut self)

Clears the Bitmap.

Examples:

use hwloc::Bitmap;

let mut bitmap = Bitmap::from_range(1,5);
assert_eq!(5, bitmap.weight());
assert_eq!(false, bitmap.is_empty());

bitmap.clear();
assert_eq!(0, bitmap.weight());
assert_eq!(true, bitmap.is_empty());

pub fn is_empty(&self) -> bool

Checks if this Bitmap has indexes set.

Examples:

use hwloc::Bitmap;

let mut bitmap = Bitmap::new();
assert_eq!(true, bitmap.is_empty());

bitmap.set(3);
assert_eq!(false, bitmap.is_empty());

bitmap.clear();
assert_eq!(true, bitmap.is_empty());

pub fn is_set(&self, id: u32) -> bool

Check if the field with the given id is set.

Examples:

use hwloc::Bitmap;

let mut bitmap = Bitmap::new();
assert_eq!(false, bitmap.is_set(2));

bitmap.set(2);
assert_eq!(true, bitmap.is_set(2));

pub fn singlify(&mut self)

Keep a single index among those set in the bitmap.

May be useful before binding so that the process does not have a chance of migrating between multiple logical CPUs in the original mask.

Examples:

use hwloc::Bitmap;

let mut bitmap = Bitmap::new();
bitmap.set_range(0, 127);
assert_eq!(128, bitmap.weight());

bitmap.invert();
assert_eq!(-1, bitmap.weight());

bitmap.singlify();
assert_eq!(1, bitmap.weight());

assert_eq!(128, bitmap.first());
assert_eq!(128, bitmap.last());

Examples found in repository

examples/bind_to_last_core.rs (line 26)

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

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

examples/bind_threads.rs (line 52)

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

    // Grab the number of cores in a block so that the lock is removed once
    // the end of the block is reached.
    let num_cores = {
        let topo_rc = topo.clone();
        let topo_locked = topo_rc.lock().unwrap();
        (*topo_locked)
            .objects_with_type(&ObjectType::Core)
            .unwrap()
            .len()
    };
    println!("Found {} cores.", num_cores);

    // Spawn one thread for each and pass the topology down into scope.
    let handles: Vec<_> = (0..num_cores)
        .map(|i| {
            let child_topo = topo.clone();
            thread::spawn(move || {
                // Get the current thread id and lock the topology to use.
                let tid = get_thread_id();
                let mut locked_topo = child_topo.lock().unwrap();

                // Thread binding before explicit set.
                let before = locked_topo.get_cpubind_for_thread(tid, CPUBIND_THREAD);

                // load the cpuset for the given core index.
                let mut bind_to = cpuset_for_core(&*locked_topo, i);

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

                // Set the binding.
                locked_topo
                    .set_cpubind_for_thread(tid, bind_to, CPUBIND_THREAD)
                    .unwrap();

                // Thread binding after explicit set.
                let after = locked_topo.get_cpubind_for_thread(tid, CPUBIND_THREAD);
                println!("Thread {}: Before {:?}, After {:?}", i, before, after);
            })
        })
        .collect();

    // Wait for all threads to complete before ending the program.
    for h in handles {
        h.join().unwrap();
    }
}

pub fn invert(&mut self)

Inverts the current Bitmap.

Examples:

use hwloc::Bitmap;

let mut bitmap = Bitmap::new();
bitmap.set(3);

assert_eq!("3", format!("{}", bitmap));
assert_eq!("0-2,4-", format!("{}", !bitmap));

pub fn first(&self) -> i32

Compute the first index (least significant bit) in this Bitmap.

Returns -1 if no index is set.

Examples:

use hwloc::Bitmap;

let bitmap = Bitmap::from_range(4,10);
assert_eq!(4, bitmap.first());

pub fn last(&self) -> i32

Compute the last index (most significant bit) in this Bitmap.

Returns -1 if no index is bitmap, or if the index bitmap is infinite.

Examples:

use hwloc::Bitmap;

let bitmap = Bitmap::from_range(4,10);
assert_eq!(10, bitmap.last());

pub fn is_full(&self) -> bool

Test whether this Bitmap is completely full.

Examples:

use hwloc::Bitmap;

let empty_bitmap = Bitmap::new();
assert_eq!(false, empty_bitmap.is_full());

let full_bitmap = Bitmap::full();
assert_eq!(true, full_bitmap.is_full());

Trait Implementations

impl Clone for Bitmap

fn clone(&self) -> Bitmap

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Bitmap

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

Formats the value using the given formatter.

impl Default for Bitmap

fn default() -> Self

Returns the “default value” for a type.

impl Display for Bitmap

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

Formats the value using the given formatter.

impl Drop for Bitmap

fn drop(&mut self)

Executes the destructor for this type.

impl FromIterator<u32> for Bitmap

fn from_iter<I: IntoIterator<Item = u32>>(iter: I) -> Bitmap

Creates a value from an iterator.

impl IntoIterator for Bitmap

type Item = u32

The type of the elements being iterated over.

type IntoIter = BitmapIntoIterator

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl Not for Bitmap

fn not(self) -> Bitmap

Returns a new bitmap which contains the negated values of the current one.

type Output = Bitmap

The resulting type after applying the ! operator.

impl PartialEq for Bitmap

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.