Skip to main content

Crate grommet_topology

Crate grommet_topology 

Source
Expand description

Hardware-aware runtime layout for grommet.

Thread-per-core placement is only as good as its picture of the machine. The previous picture was a flat list of logical CPU identifiers split by taking the first n, which assumes identifier adjacency means hardware adjacency. It does not, on any machine worth tuning for.

Discovery is libhwloc, unmodified and unwrapped. It already knows the cache hierarchy, NUMA distances, Windows processor groups and the cpukinds ranking for hybrid parts, so there is no local model to drift from it: plan() reads an hwlocality::Topology directly.

Two things hwloc does not answer are supplied here:

  • CFS bandwidth limits. hwloc reports which CPUs you may run on, not how much CPU time you may use. A container capped at two cores on a ninety-six core host still sees ninety-six. See cgroup.
  • Whether this build is fit to be measured. A debug build runs the scheduler’s invariant check every reactor iteration.
use grommet_topology::{Workload, detect};

let layout = detect(&Workload::default()).expect("read this machine");
for note in &layout.notes {
    eprintln!("topology: {note}");
}

The plan is then applied by the threads it describes, each binding itself as it starts (see bind), and the split it chose can be checked against what the workload turned out to need (see calibrate): offline, as a configuration change, never as a live adjustment.

§Testing without the hardware

hwloc builds a topology from a synthetic description or an XML capture, so a two-socket SMT server, a throttled container or a hybrid laptop are all unit tests on whatever machine is to hand. See plan() for how.

§Without hwloc

The hwloc feature is on by default and is what makes any of the above true. Turning it off replaces discovery with fallback::detect, which plans from std::thread::available_parallelism alone: one memory node, no SMT knowledge, and no binding. Every type here stays, so code that plans and starts a runtime compiles either way: it simply gets a layout that admits it is guessing.

Re-exports§

pub use bind::Bound;
pub use calibrate::Advice;
pub use calibrate::Observation;
pub use calibrate::Verdict;
pub use cgroup::Quota;
pub use cgroup::QuotaSource;
pub use plan::OffloadPool;
pub use plan::Plan;
pub use plan::ShardPlacement;
pub use plan::Workload;
pub use plan::plan;
pub use plan::plan_shared;

Modules§

bind
Making a plan take effect.
calibrate
Choosing compute_fraction from measurement instead of from a guess.
cgroup
CFS bandwidth limits, the one thing hwloc cannot tell us.
plan
Turning a machine into a runtime layout.

Functions§

detect
Plan a layout for the machine this process is running on.