parmesan-par2 0.6.0

Fast, standalone PAR2 (Reed-Solomon) creation, verification and repair tool
Documentation
pub mod affine;
pub mod affine2x;
pub mod altmap;
pub mod create;
pub mod decoder;
pub mod encoder;
pub mod gf16;
pub mod gf16_mac;
pub mod layout;
pub mod matrix;
pub mod ops;
pub mod packet;
pub mod packet_reader;
pub mod recovery_set;
pub mod repair;
pub mod shuffle2x;
#[cfg(test)]
pub(crate) mod test_support;
pub mod verify;
pub mod worker;
pub mod yenc;

pub use encoder::{
    affine2x_buffer_size, affine_buffer_size, altmap_buffer_size, shuffle2x_buffer_size,
};

/// Shown by `--version` and banners.
pub const DISPLAY_VERSION: &str = env!("CARGO_PKG_VERSION");

/// Multiplication backend for the Reed-Solomon encoder.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, clap::ValueEnum)]
pub enum SimdPath {
    /// Auto-detect the fastest supported path for the current CPU.
    #[default]
    Auto,
    /// Pure Rust scalar implementation (no SIMD).
    Scalar,
    /// Intel/AMD SSSE3 (128-bit shuffles).
    Ssse3,
    /// Intel/AMD AVX2 (256-bit shuffles).
    Avx2,
    /// Intel Ice Lake+ / Sapphire Rapids+ AVX2 with GFNI.
    Avx2Gfni,
    /// Intel Ice Lake+ / Sapphire Rapids+ AVX-512 with GFNI.
    Avx512Gfni,
    /// AVX-512 VL/BW nibble shuffle (no GFNI — Skylake-X / Cascade Lake).
    Avx512Shuffle,
    /// ARM NEON (AArch64 128-bit shuffles).
    Neon,
}

impl std::fmt::Display for SimdPath {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Auto => write!(f, "auto"),
            Self::Scalar => write!(f, "scalar"),
            Self::Ssse3 => write!(f, "ssse3"),
            Self::Avx2 => write!(f, "avx2"),
            Self::Avx2Gfni => write!(f, "avx2-gfni"),
            Self::Avx512Gfni => write!(f, "avx512-gfni"),
            Self::Avx512Shuffle => write!(f, "avx512-shuffle"),
            Self::Neon => write!(f, "neon"),
        }
    }
}

/// Which recovery-buffer layout `parmesan create` builds.
///
/// `smart` is the auto path (Affine512 packed on AVX-512+GFNI).
/// `affine512` forces that layout even if `smart` would pick another.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, clap::ValueEnum)]
pub enum EncoderLayout {
    #[default]
    Smart,
    Normal,
    Affine,
    Affine512,
    Shuffle2x,
}

impl std::fmt::Display for EncoderLayout {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Smart => write!(f, "smart"),
            Self::Normal => write!(f, "normal"),
            Self::Affine => write!(f, "affine"),
            Self::Affine512 => write!(f, "affine512"),
            Self::Shuffle2x => write!(f, "shuffle2x"),
        }
    }
}

/// Returns the name of the SIMD path that the PAR2 encoder will use at runtime.
pub fn detect_simd() -> &'static str {
    #[cfg(target_arch = "x86_64")]
    if std::is_x86_feature_detected!("avx512f")
        && std::is_x86_feature_detected!("avx512bw")
        && std::is_x86_feature_detected!("gfni")
    {
        return "AVX-512/GFNI";
    }
    #[cfg(target_arch = "x86_64")]
    if std::is_x86_feature_detected!("avx2") && std::is_x86_feature_detected!("gfni") {
        return "AVX2/GFNI";
    }
    #[cfg(target_arch = "x86_64")]
    if std::is_x86_feature_detected!("avx512f") && std::is_x86_feature_detected!("avx512bw") {
        return "AVX-512/Shuffle";
    }
    #[cfg(target_arch = "x86_64")]
    if std::is_x86_feature_detected!("avx2") {
        return "AVX2";
    }
    #[cfg(target_arch = "x86_64")]
    if std::is_x86_feature_detected!("ssse3") {
        return "SSSE3";
    }
    #[cfg(target_arch = "aarch64")]
    {
        return "NEON";
    }
    #[allow(unreachable_code)]
    "scalar"
}

/// Number of physical CPU cores, derived from `/proc/cpuinfo` by counting
/// distinct `(physical id, core id)` pairs. Falls back to the logical CPU
/// count when that information is unavailable.
pub fn physical_core_count() -> usize {
    #[cfg(target_os = "linux")]
    {
        use std::collections::HashSet;
        if let Ok(info) = std::fs::read_to_string("/proc/cpuinfo") {
            let mut seen: HashSet<(String, String)> = HashSet::new();
            let (mut phys, mut core): (Option<String>, Option<String>) = (None, None);
            for line in info.lines() {
                if line.trim().is_empty() {
                    if let (Some(p), Some(c)) = (phys.take(), core.take()) {
                        seen.insert((p, c));
                    }
                } else if let Some((key, val)) = line.split_once(':') {
                    match key.trim() {
                        "physical id" => phys = Some(val.trim().to_string()),
                        "core id" => core = Some(val.trim().to_string()),
                        _ => {}
                    }
                }
            }
            if !seen.is_empty() {
                return seen.len();
            }
        }
    }
    std::thread::available_parallelism()
        .map(|n| n.get())
        .unwrap_or(1)
}

/// Number of physical cores on hybrid CPUs.
/// On hybrid CPUs (Intel 12th gen+), detects P-cores (high-performance) vs
/// E-cores (efficiency) via Linux topology: P-cores have 2+ thread_siblings
/// (hyperthreading), E-cores have 1 (standalone).
///
/// Returns count of P-core leaders + E-cores (one thread per physical core)
/// for work distribution. Hyperthreads are excluded as they contend for the
/// same execution ports and add noise on CPU-bound workloads.
/// On non-hybrid CPUs falls back to [`physical_core_count`].
///
/// The topology above describes the whole host, so the result is capped at
/// [`std::thread::available_parallelism`], which honours the CPU affinity
/// mask and cgroup CPU quotas. A process confined to 4 CPUs of a 64-core
/// host gets 4, not 64.
pub fn performance_core_count() -> usize {
    let usable = std::thread::available_parallelism()
        .map(|n| n.get())
        .unwrap_or(usize::MAX);
    host_performance_core_count().min(usable).max(1)
}

/// [`performance_core_count`] before the cap at the usable CPU count.
fn host_performance_core_count() -> usize {
    #[cfg(target_os = "linux")]
    {
        use std::collections::HashSet;

        let Ok(entries) = std::fs::read_dir("/sys/devices/system/cpu") else {
            return physical_core_count();
        };

        let mut paired_leaders: HashSet<usize> = HashSet::new();
        let mut solo: HashSet<usize> = HashSet::new();

        for entry in entries.flatten() {
            let name = entry.file_name();
            let name_s = name.to_string_lossy();
            let Some(cpu_num) = name_s
                .strip_prefix("cpu")
                .and_then(|s| s.parse::<usize>().ok())
            else {
                continue;
            };
            let sib_path = entry.path().join("topology/thread_siblings_list");
            let Ok(sib) = std::fs::read_to_string(sib_path) else {
                continue;
            };
            let leader = sib
                .trim()
                .split([',', '-'])
                .next()
                .and_then(|s| s.parse::<usize>().ok())
                .unwrap_or(cpu_num);
            let count = sib.trim().split([',', '-']).count();
            if count >= 2 {
                paired_leaders.insert(leader);
            } else {
                solo.insert(cpu_num);
            }
        }

        if !paired_leaders.is_empty() && !solo.is_empty() {
            return paired_leaders.len() + solo.len();
        }
    }
    physical_core_count()
}

#[cfg(test)]
mod tests {
    #[test]
    fn performance_core_count_stays_within_usable_cpus() {
        let usable = std::thread::available_parallelism().map_or(usize::MAX, |n| n.get());
        let cores = super::performance_core_count();
        assert!(
            (1..=usable).contains(&cores),
            "{cores} cores, {usable} usable"
        );
    }
}