dijkstra3d-core 0.1.0

Voxel-grid Dijkstra and rolling-ball invalidation, ported from seung-lab/dijkstra3d and seung-lab/kimimaro
Documentation
//! Best-effort P-core-aware rayon thread pools for the batch engine (opt-in).
//!
//! This Linux-specific optimization is not required for correctness. CPU-list
//! ordering and affinity support vary by host; failed affinity calls leave the
//! worker usable but unpinned.

use std::collections::HashMap;
use std::sync::{Mutex, OnceLock};

/// Read the P-core logical-CPU list from sysfs using the host's alternating
/// logical-thread numbering convention.
///
/// Returns `None` when the Linux hybrid-core list is unavailable. The returned
/// order is a scheduling hint, not a portable topology guarantee.
pub fn pcore_pin_order() -> Option<Vec<usize>> {
    static ORDER: OnceLock<Option<Vec<usize>>> = OnceLock::new();
    ORDER
        .get_or_init(|| {
            let raw = std::fs::read_to_string("/sys/devices/cpu_core/cpus").ok()?;
            let mut cpus = parse_cpu_list(&raw);
            if cpus.is_empty() {
                return None;
            }
            cpus.sort_unstable();
            cpus.dedup();

            let evens = cpus.iter().copied().step_by(2);
            let odds = cpus.iter().copied().skip(1).step_by(2);
            Some(evens.chain(odds).collect())
        })
        .clone()
}

/// Number of distinct physical P-cores (best-effort).
pub fn physical_pcore_count() -> Option<usize> {
    pcore_pin_order().map(|o| o.len().div_ceil(2))
}

/// Parse a Linux cpulist like `"0-15"` or `"0-3,8-11"` into explicit ids.
fn parse_cpu_list(s: &str) -> Vec<usize> {
    let mut out = Vec::new();
    for part in s.trim().split(',') {
        let part = part.trim();
        if part.is_empty() {
            continue;
        }
        if let Some((a, b)) = part.split_once('-') {
            if let (Ok(a), Ok(b)) = (a.trim().parse::<usize>(), b.trim().parse::<usize>()) {
                out.extend(a..=b);
            }
        } else if let Ok(v) = part.parse::<usize>() {
            out.push(v);
        }
    }
    out
}

/// Pin the *calling* thread to a single logical CPU (best-effort; errors and
/// non-Linux targets are silently ignored).
#[cfg(target_os = "linux")]
fn pin_current_thread(cpu: usize) {
    unsafe {
        let mut set: libc::cpu_set_t = std::mem::zeroed();
        libc::CPU_SET(cpu, &mut set);
        // tid 0 == current thread.
        libc::sched_setaffinity(0, std::mem::size_of::<libc::cpu_set_t>(), &set);
    }
}

#[cfg(not(target_os = "linux"))]
fn pin_current_thread(_cpu: usize) {}

/// A process-lifetime rayon pool of `n` workers, cached by `n`.
///
/// On supported Linux hosts, each worker attempts to pin itself to the matching
/// entry in `pcore_pin_order()[..n]`. Affinity failure is deliberately
/// best-effort and does not affect pathfinding results.
pub fn perf_pool(n: usize) -> Option<&'static rayon::ThreadPool> {
    if n == 0 {
        return None;
    }
    let order = pcore_pin_order()?;
    if n > order.len() {
        return None; // would oversubscribe P-cores / spill to E-cores
    }

    static POOLS: OnceLock<Mutex<HashMap<usize, &'static rayon::ThreadPool>>> = OnceLock::new();
    let cache = POOLS.get_or_init(|| Mutex::new(HashMap::new()));
    let mut guard = cache
        .lock()
        .unwrap_or_else(|poisoned| poisoned.into_inner());
    if let Some(pool) = guard.get(&n) {
        return Some(*pool);
    }

    let pins: Vec<usize> = order[..n].to_vec();
    let pool = rayon::ThreadPoolBuilder::new()
        .num_threads(n)
        .thread_name(|i| format!("d3d-batch-p{i}"))
        .start_handler(move |i| pin_current_thread(pins[i]))
        .build()
        .ok()?;
    let leaked: &'static rayon::ThreadPool = Box::leak(Box::new(pool));
    guard.insert(n, leaked);
    Some(leaked)
}

/// Resolve the pool the batch should run on for a caller `threads` request.
pub fn resolve_batch_pool(threads: Option<usize>) -> Option<&'static rayon::ThreadPool> {
    match threads {
        None | Some(0) => None,
        Some(n) => perf_pool(n),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn parse_cpu_list_ranges_and_singletons() {
        assert_eq!(parse_cpu_list("0-15").len(), 16);
        assert_eq!(parse_cpu_list("0-3,8-11"), vec![0, 1, 2, 3, 8, 9, 10, 11]);
        assert_eq!(parse_cpu_list("5"), vec![5]);
        assert_eq!(parse_cpu_list(""), Vec::<usize>::new());
        assert_eq!(parse_cpu_list(" 2 , 4 "), vec![2, 4]);
    }

    #[test]
    fn pin_order_puts_physical_reps_first() {
        // Simulate the parse+reorder used by pcore_pin_order for "0-15".
        let mut cpus = parse_cpu_list("0-15");
        cpus.sort_unstable();
        let evens: Vec<usize> = cpus.iter().copied().step_by(2).collect();
        assert_eq!(evens, vec![0, 2, 4, 6, 8, 10, 12, 14]);
    }

    #[test]
    fn resolve_zero_forces_global() {
        assert!(resolve_batch_pool(Some(0)).is_none());
    }

    #[test]
    fn perf_pool_smoke_if_hybrid() {
        // On a detected hybrid host a small pool builds and runs; elsewhere the
        // test verifies that the unavailable-pool path is coherent.
        if let Some(pool) = perf_pool(2) {
            let sum: usize = pool.install(|| {
                use rayon::prelude::*;
                (0..1000usize).into_par_iter().sum()
            });
            assert_eq!(sum, 499_500);
            // Cached: same pointer on a second request.
            assert!(std::ptr::eq(pool, perf_pool(2).unwrap()));
        }
    }
}