Add: Bind the measured fabric to Rust and Zig

Both bindings gain a `Fabric` type in their scheduling modules - the
mirrors of the C++ scheduling layer where `measured_fabric` lives, so
no new files appear. Rust exposes `Fabric::new` and
`try_harvest(&mut self, &Topology, &mut ThreadPool)`, keeping the
topology shareable during measurement; Zig exposes `Fabric.init`,
`deinit`, and `tryHarvest(topo, pool)`. Each carries the five queries
- memoryLatency, memoryBandwidth, memoryDistance, memoryLevelIn, and
the levels count - and each module's test harvests through a live pool
and asserts the local edge, the distance anchor, and the pre-harvest
zeros. The Topology-side metric getters and the old
measure-memory-distances entry points are gone from both languages,
matching the C header, and the extern lists are regrouped flat in the
header's declaration order.

rust/forkunion.rs

@@ -10,9 +10,10 @@
 //! principles while leveraging NUMA-aware optimizations and CPU-specific busy-waiting instructions.
 //!
 //! The wrapper mirrors the C++ core's header layout: [`topology`] for the hardware view, [`types`] for
-//! portable building blocks, [`allocators`] for NUMA-aware allocation, [`scheduling`] for the thread pool
-//! and its dispatch primitives, and [`parallel`] for the Rayon-style parallel iterators. Every public
-//! symbol is re-exported here, so `use forkunion::*` resolves exactly as it did before the split.
+//! portable building blocks, [`allocators`] for NUMA-aware allocation, [`scheduling`] for the thread pool,
+//! its dispatch primitives, and the measured memory fabric, and [`parallel`] for the Rayon-style parallel
+//! iterators. Every public symbol is re-exported here, so `use forkunion::*` resolves exactly as it did
+//! before the split.
 
 #![no_std]
 

rust/forkunion/scheduling.rs

@@ -1,15 +1,16 @@
-//! The thread pool and its dispatch primitives - spawn, scoped joins, and parallel loops.
+//! The thread pool and its dispatch primitives - spawn, scoped joins, parallel loops - and the
+//! measured memory fabric those pools can harvest.
 //!
-//! Owns the `fu_pool_*` FFI; mirrors the C++ `flat`/scheduling layer.
+//! Owns the `fu_pool_*` and `fu_fabric_*` FFI; mirrors the C++ `flat`/`distributed` scheduling layer.
 
 use crate::parallel::{ParallelIterator, ParallelSchedule};
-use crate::topology::{CallerExclusivity, Capabilities, Error, Topology};
+use crate::topology::{
+    CallerExclusivity, Capabilities, ComputeDomain, Error, MemoryDomain, Topology,
+};
 use crate::types::{IndexedSplit, Prong, SafePtr, SyncMutPtr};
 use core::ffi::{c_char, c_int, c_void};
 
-// C FFI declarations
 extern "C" {
-    // Pool lifecycle & introspection
     fn fu_pool_new(name: *const c_char, allowed: u32) -> *mut c_void;
     fn fu_pool_delete(pool: *mut c_void);
     fn fu_pool_spawn(
@@ -37,7 +38,6 @@ extern "C" {
     fn fu_pool_sleep(pool: *mut c_void, micros: usize);
     fn fu_pool_terminate(pool: *mut c_void);
 
-    // Parallel dispatch
     #[allow(dead_code)]
     fn fu_pool_for_threads(
         pool: *mut c_void,
@@ -63,7 +63,6 @@ extern "C" {
         context: *mut c_void,
     );
 
-    // Generation tokens
     fn fu_pool_unsafe_for_threads(
         pool: *mut c_void,
         callback: extern "C" fn(*mut c_void, usize, usize),
@@ -72,6 +71,27 @@ extern "C" {
     fn fu_pool_is_complete(pool: *mut c_void, generation: usize) -> c_int;
     fn fu_pool_unsafe_join(pool: *mut c_void, generation: usize);
     fn fu_pool_capabilities(pool: *mut c_void) -> u32;
+
+    fn fu_fabric_new() -> *mut c_void;
+    fn fu_fabric_delete(fabric: *mut c_void);
+    fn fu_fabric_harvest(topology: *mut c_void, pool: *mut c_void, fabric: *mut c_void) -> c_int;
+    fn fu_fabric_memory_latency(
+        fabric: *mut c_void,
+        compute_domain_index: usize,
+        memory_domain_index: usize,
+    ) -> usize;
+    fn fu_fabric_memory_bandwidth(
+        fabric: *mut c_void,
+        compute_domain_index: usize,
+        memory_domain_index: usize,
+    ) -> usize;
+    fn fu_fabric_memory_distance(
+        fabric: *mut c_void,
+        compute_domain_index: usize,
+        memory_domain_index: usize,
+    ) -> usize;
+    fn fu_fabric_memory_level_in(fabric: *mut c_void, memory_domain_index: usize) -> usize;
+    fn fu_fabric_memory_levels_count(fabric: *mut c_void) -> usize;
 }
 
 /// Minimalistic, fixed-size thread-pool for blocking scoped parallelism.
@@ -746,6 +766,108 @@ impl Drop for ThreadPool {
     }
 }
 
+/// The measured memory fabric - what this process observed, as opposed to the structure a
+/// [`Topology`] declares. Two query families: edge queries `(initiator, target)` describe one
+/// interconnect link; medium queries `(target)` describe the memory pool itself, independent of
+/// any initiator.
+///
+/// Completes the `try_harvest` pipeline: a [`Topology`] is harvested first and stays immutable
+/// (and shareable), a [`ThreadPool`] spawns on it, and the fabric then harvests through that
+/// pool's pinned workers, snapshotting what it needs so the topology may be dropped after.
+/// Before a harvest every query answers 0, and
+/// [`memory_levels_count`](Self::memory_levels_count) answers 1.
+///
+/// # Examples
+///
+/// ```rust,no_run
+/// use forkunion::*;
+/// let topology = Topology::new().unwrap();
+/// let mut pool = spawn(&topology, 4);
+/// let mut fabric = Fabric::new().unwrap();
+/// if fabric.try_harvest(&topology, &mut pool) {
+///     let local = topology.local_memory_of(ComputeDomain(0));
+///     assert!(fabric.memory_latency(ComputeDomain(0), local) > 0);
+/// }
+/// ```
+pub struct Fabric {
+    inner: *mut c_void,
+}
+
+unsafe impl Send for Fabric {}
+unsafe impl Sync for Fabric {}
+
+impl Fabric {
+    /// Creates an empty, unharvested fabric.
+    pub fn new() -> Result<Fabric, Error> {
+        let inner = unsafe { fu_fabric_new() };
+        if inner.is_null() {
+            return Err(Error::CreationFailed);
+        }
+        Ok(Fabric { inner })
+    }
+
+    /// Measures the memory fabric through the pool's pinned workers, replacing any previous
+    /// harvest; the `topology` is only read.
+    ///
+    /// Returns `false` on allocation failure, or for a pool whose workers are not pinned per
+    /// domain - one restricted below [`Capabilities::PLACE_MEMORY_ON_DOMAIN`] or pinned via
+    /// [`ThreadPool::try_spawn_on`]; the fabric is then left empty, never half-written. Not
+    /// thread-safe: it dispatches on the pool and rebuilds `self`, so call it between task
+    /// batches. Expect seconds of runtime on large fabrics.
+    pub fn try_harvest(&mut self, topology: &Topology, pool: &mut ThreadPool) -> bool {
+        unsafe { fu_fabric_harvest(topology.raw(), pool.inner, self.inner) != 0 }
+    }
+
+    /// Returns the measured dependent-load latency (nanoseconds) on an edge - the best recording;
+    /// 0 before a harvest, for an edge no worker could reach, or an out-of-range index.
+    pub fn memory_latency(
+        &self,
+        compute_domain: ComputeDomain,
+        memory_domain: MemoryDomain,
+    ) -> usize {
+        unsafe { fu_fabric_memory_latency(self.inner, compute_domain.get(), memory_domain.get()) }
+    }
+
+    /// Returns the measured saturated read bandwidth (MB/s) on an edge, streamed by all the
+    /// initiator domain's workers at once - the best recording; 0 if unreached or out of range.
+    pub fn memory_bandwidth(
+        &self,
+        compute_domain: ComputeDomain,
+        memory_domain: MemoryDomain,
+    ) -> usize {
+        unsafe { fu_fabric_memory_bandwidth(self.inner, compute_domain.get(), memory_domain.get()) }
+    }
+
+    /// Returns the relative access distance on an edge (10 = local, per the SLIT convention):
+    /// the measured latency ratio to the initiator's local domain, clamped so local carries the
+    /// row's minimum; unwalked edges fall back to 10-local / 20-remote.
+    pub fn memory_distance(
+        &self,
+        compute_domain: ComputeDomain,
+        memory_domain: MemoryDomain,
+    ) -> usize {
+        unsafe { fu_fabric_memory_distance(self.inner, compute_domain.get(), memory_domain.get()) }
+    }
+
+    /// Returns the derived speed class of a memory domain (lower = faster: HBM < DDR < CXL),
+    /// keyed by the best bandwidth any initiator sustains to it, ties split by the best latency.
+    pub fn memory_level_in(&self, memory_domain: MemoryDomain) -> usize {
+        unsafe { fu_fabric_memory_level_in(self.inner, memory_domain.get()) }
+    }
+
+    /// Returns the number of distinct derived memory tiers, the memory-axis twin of
+    /// [`Topology::compute_levels_count`]; 1 on single-tier systems and before a harvest.
+    pub fn memory_levels_count(&self) -> usize {
+        unsafe { fu_fabric_memory_levels_count(self.inner) }
+    }
+}
+
+impl Drop for Fabric {
+    fn drop(&mut self) {
+        unsafe { fu_fabric_delete(self.inner) };
+    }
+}
+
 /// A synchronization guard that waits for all threads to finish the broadcasted closure.
 ///
 /// The lifecycle is keyed on the pool's exclusivity:
@@ -1422,6 +1544,29 @@ mod tests {
         }
     }
 
+    #[cfg_attr(miri, ignore)]
+    #[test]
+    fn fabric_harvest_fills_edges() {
+        let topology = Topology::new().unwrap();
+        let mut pool = spawn(&topology, hw_threads());
+        let mut fabric = Fabric::new().unwrap();
+
+        // An unharvested fabric answers zeros and a single tier.
+        assert_eq!(fabric.memory_latency(ComputeDomain(0), MemoryDomain(0)), 0);
+        assert_eq!(fabric.memory_levels_count(), 1);
+
+        if !fabric.try_harvest(&topology, &mut pool) {
+            return; // ? A flat pool without domain placement has no fabric to walk
+        }
+        // Every reachable edge must carry sane observations; emulated-NUMA guests may
+        // measure equal local and remote costs, so nothing stronger is asserted.
+        let local = topology.local_memory_of(ComputeDomain(0));
+        assert!(fabric.memory_latency(ComputeDomain(0), local) > 0);
+        assert!(fabric.memory_bandwidth(ComputeDomain(0), local) > 0);
+        assert_eq!(fabric.memory_distance(ComputeDomain(0), local), 10);
+        assert!(fabric.memory_levels_count() >= 1);
+    }
+
     #[cfg_attr(miri, ignore)]
     #[test]
     fn generation_raw_unsafe_api() {

rust/forkunion/topology.rs

@@ -4,21 +4,17 @@
 
 use core::ffi::{c_char, c_int, c_void};
 
-// C FFI declarations
 extern "C" {
-    // Library metadata
     fn fu_version_major() -> c_int;
     fn fu_version_minor() -> c_int;
     fn fu_version_patch() -> c_int;
     fn fu_comptime_capabilities() -> u32;
     fn fu_runtime_capabilities() -> u32;
     fn fu_name_capabilities(caps: u32, buf: *mut c_char, len: usize) -> usize;
 
-    // Topology handle lifecycle
     fn fu_topology_new() -> *mut c_void;
     fn fu_topology_delete(topology: *mut c_void);
 
-    // Compute topology
     fn fu_logical_cores_count_in(topology: *mut c_void, compute_domain_index: usize) -> usize;
     fn fu_logical_cores_count(topology: *mut c_void) -> usize;
     fn fu_compute_domains_count(topology: *mut c_void) -> usize;
@@ -27,37 +23,14 @@ extern "C" {
     fn fu_compute_capacity_in(topology: *mut c_void, compute_domain_index: usize) -> usize;
     fn fu_compute_cache_bytes_in(topology: *mut c_void, compute_domain_index: usize) -> usize;
 
-    // Memory topology
     fn fu_memory_domains_count(topology: *mut c_void) -> usize;
-    fn fu_memory_level_in(topology: *mut c_void, memory_domain_index: usize) -> usize;
-    fn fu_memory_levels_count(topology: *mut c_void) -> usize;
-
-    // Affinity
     fn fu_local_memory_of(topology: *mut c_void, compute_domain_index: usize) -> usize;
-    fn fu_memory_distance(
-        topology: *mut c_void,
-        compute_domain_index: usize,
-        memory_domain_index: usize,
-    ) -> usize;
-    fn fu_memory_bandwidth(
-        topology: *mut c_void,
-        compute_domain_index: usize,
-        memory_domain_index: usize,
-    ) -> usize;
-    fn fu_memory_latency(
-        topology: *mut c_void,
-        compute_domain_index: usize,
-        memory_domain_index: usize,
-    ) -> usize;
-
     fn fu_volume_ram_in(topology: *mut c_void, memory_domain_index: usize) -> usize;
     fn fu_volume_ram(topology: *mut c_void) -> usize;
     fn fu_volume_huge_pages_in(topology: *mut c_void, memory_domain_index: usize) -> usize;
     fn fu_volume_huge_pages(topology: *mut c_void) -> usize;
     fn fu_huge_pages_count_in(topology: *mut c_void, memory_domain_index: usize) -> usize;
     fn fu_huge_pages_count(topology: *mut c_void) -> usize;
-
-    // Allocation
     fn fu_memory_domain_id_at_index(topology: *mut c_void, memory_domain_index: usize) -> i32;
 }
 
@@ -396,51 +369,14 @@ impl Topology {
         MemoryDomainId(unsafe { fu_memory_domain_id_at_index(self.inner, memory_domain.get()) })
     }
 
-    /// Returns the performance level of a memory domain (lower = faster: HBM < DDR < CXL).
-    pub fn memory_level_in(&self, memory_domain: MemoryDomain) -> usize {
-        unsafe { fu_memory_level_in(self.inner, memory_domain.get()) }
-    }
-
-    /// Returns the number of distinct memory tiers, the memory-axis twin of
-    /// [`compute_levels_count`](Self::compute_levels_count).
-    ///
-    /// Reports 1 on single-tier systems, and 2+ where HBM, DDR, and CXL are mixed.
-    pub fn memory_levels_count(&self) -> usize {
-        unsafe { fu_memory_levels_count(self.inner) }
-    }
-
     /// Returns the memory domain nearest a given compute domain (its local allocation target).
+    ///
+    /// Performance - tiers, latencies, bandwidths, distances - is not the topology's to declare:
+    /// harvest a [`Fabric`](crate::Fabric) to measure it in-process.
     pub fn local_memory_of(&self, compute_domain: ComputeDomain) -> MemoryDomain {
         MemoryDomain(unsafe { fu_local_memory_of(self.inner, compute_domain.get()) })
     }
 
-    /// Returns the relative access distance from a compute domain to a memory domain (10 = local).
-    pub fn memory_distance(
-        &self,
-        compute_domain: ComputeDomain,
-        memory_domain: MemoryDomain,
-    ) -> usize {
-        unsafe { fu_memory_distance(self.inner, compute_domain.get(), memory_domain.get()) }
-    }
-
-    /// Returns the HMAT read bandwidth (MB/s) from a compute domain to a memory domain, or 0 if unknown.
-    pub fn memory_bandwidth(
-        &self,
-        compute_domain: ComputeDomain,
-        memory_domain: MemoryDomain,
-    ) -> usize {
-        unsafe { fu_memory_bandwidth(self.inner, compute_domain.get(), memory_domain.get()) }
-    }
-
-    /// Returns the HMAT read latency (nanoseconds) from a compute domain to a memory domain, or 0 if unknown.
-    pub fn memory_latency(
-        &self,
-        compute_domain: ComputeDomain,
-        memory_domain: MemoryDomain,
-    ) -> usize {
-        unsafe { fu_memory_latency(self.inner, compute_domain.get(), memory_domain.get()) }
-    }
-
     /// Returns the RAM volume (bytes) held by a given memory domain (0 if out of range).
     pub fn volume_ram_in(&self, memory_domain: MemoryDomain) -> usize {
         unsafe { fu_volume_ram_in(self.inner, memory_domain.get()) }
@@ -559,12 +495,10 @@ pub(crate) mod tests {
         let compute_domains = topology.compute_domains_count();
         let compute_levels = topology.compute_levels_count();
         let memory_domains = topology.memory_domains_count();
-        let memory_levels = topology.memory_levels_count();
         assert!(compute_domains > 0 && memory_domains > 0);
 
         // Levels are dense ranks over domains, so they can never outnumber them.
         assert!(compute_levels <= compute_domains);
-        assert!(memory_levels <= memory_domains);
 
         for domain in (0..compute_domains).map(ComputeDomain) {
             assert!(topology.compute_level_in(domain) < compute_levels.max(1));
@@ -573,9 +507,6 @@ pub(crate) mod tests {
             let _capacity = topology.compute_capacity_in(domain);
             let _cache_bytes = topology.compute_cache_bytes_in(domain);
         }
-        for domain in (0..memory_domains).map(MemoryDomain) {
-            assert!(topology.memory_level_in(domain) < memory_levels.max(1));
-        }
 
         // Out-of-range indices must saturate to 0 rather than trap or read past the topology.
         assert_eq!(

zig/forkunion.zig

@@ -68,6 +68,7 @@ pub const ShardedArray = allocators.ShardedArray;
 
 // scheduling
 pub const Pool = scheduling.Pool;
+pub const Fabric = scheduling.Fabric;
 
 test { // pull each module's tests into `zig build test`
     _ = @import("forkunion/topology.zig");