Crate hwloc

Rust Bindings for the Hwloc library

This library is a rust binding to the hwloc C library, which provides a portable abstraction of the hierarchical topology of modern architectures, including NUMA memory nodes, sockets, shared caches, cores and simultaneous multithreading.

Usage

First, add the following to your Cargo.toml:

[dependencies]
hwloc = "0.3.0"

Next, add this to your crate root:

extern crate hwloc;

Here is a quick example which walks the Topology and prints it out:

extern crate hwloc;

use hwloc::Topology;

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

    for i in 0..topo.depth() {
        println!("*** Objects at level {}", i);

        for (idx, object) in topo.objects_at_depth(i).iter().enumerate() {
            println!("{}: {}", idx, object);
        }
    }
}

You can also look at more examples, if you want to run them check out the next section below.

Running Examples

The library ships with examples, and to run them you need to clone the repository and then run them through cargo run --example=.

$ git clone https://github.com/daschl/hwloc-rs.git
$ cd hwloc-rs

To run an example (which will download the dependencies and build it) you can use cargo run -example=:

$ cargo run --example=walk_tree
   Compiling libc v0.2.3
   ...
   Compiling hwloc v0.2.0 (file:///vagrant/hwloc-rs)
     Running `target/debug/examples/walk_tree`
*** Printing overall tree
Machine (490MB): #0
 Socket (): #0
  L2d (6144KB): #4294967295
   L1d (32KB): #4294967295
    Core (): #0
     PU (): #0
  L1d (32KB): #4294967295
    Core (): #1
     PU (): #1

License

This project uses the MIT license, please see the LICENSE file for more information.

Structs

Bitmap	A generic bitmap, understood by hwloc.
CpuBindFlags	Process/Thread binding flags.
MemBindPolicy
Topology
TopologyCpuBindSupport	Flags describing actual PU binding support for this topology.
TopologyDiscoverySupport
TopologyMemBindSupport	Flags describing actual memory binding support for this topology.
TopologyObject
TopologyObjectMemory
TopologySupport

Enums

CpuBindError
ObjectType	Represents the type of a topology object.
TopologyFlag
TypeDepthError

Constants

CPUBIND_NO_MEMBIND	Avoid any effect on memory binding.
CPUBIND_PROCESS	Bind all threads of the current (possibly) multithreaded process.
CPUBIND_STRICT	Request for strict binding from the OS.
CPUBIND_THREAD	Bind current thread of current process.
MEMBIND_BIND	Allocate memory on the specified nodes.
MEMBIND_DEFAULT	Reset the memory allocation policy to the system default. Depending on the operating system, this may correspond to MEMBIND_FIRSTTOUCH (Linux), or MEMBIND_BIND (AIX, HP-UX, OSF, Solaris, Windows).
MEMBIND_FIRSTTOUCH	Allocate memory but do not immediately bind it to a specific locality. Instead, each page in the allocation is bound only when it is first touched. Pages are individually bound to the local NUMA node of the first thread that touches it. If there is not enough memory on the node, allocation may be done in the specified cpuset before allocating on other nodes.
MEMBIND_INTERLEAVE	Allocate memory on the given nodes in an interleaved / round-robin manner. The precise layout of the memory across multiple NUMA nodes is OS/system specific. Interleaving can be useful when threads distributed across the specified NUMA nodes will all be accessing the whole memory range concurrently, since the interleave will then balance the memory references.
MEMBIND_MIXED	Returned by get_membind() functions when multiple threads or parts of a memory area have differing memory binding policies.
MEMBIND_NEXTTOUCH	For each page bound with this policy, by next time it is touched (and next time only), it is moved from its current location to the local NUMA node of the thread where the memory reference occurred (if it needs to be moved at all).
MEMBIND_REPLICATE	Replicate memory on the given nodes; reads from this memory will attempt to be serviced from the NUMA node local to the reading thread. Replicating can be useful when multiple threads from the specified NUMA nodes will be sharing the same read-only data.

Type Definitions

CpuSet	A CpuSet is a Bitmap whose bits are set according to CPU physical OS indexes.
NodeSet	A NodeSet is a Bitmap whose bits are set according to NUMA memory node physical OS indexes.