zeppelin_embed/scan/
parallel.rs

1//! Persistent-pool scan controls, outcomes, and CPU-capacity detection.
2
3use super::ScanError;
4
5/// Runtime controls for the extended exact scan.
6#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
7pub struct ScanOptions {
8    /// Requested worker count. Zero explicitly selects all detected physical
9    /// performance cores; a nonzero request is capped at that count.
10    pub thread_budget: usize,
11}
12
13/// Deterministic companion counters for one completed scan.
14#[derive(Clone, Debug, Eq, PartialEq)]
15pub struct ScanStats {
16    /// Logical row-coordinate multiply-accumulates scored by the scan. Packed
17    /// Bit4 batches score every row in a four-row window before applying masks,
18    /// so their masked lanes are included.
19    pub dims_touched: u64,
20    /// Row-major payload bytes read by scoring. Row-factor records are excluded.
21    /// This counter is a pure function of the request and scan options.
22    pub bytes_read: u64,
23    /// Persistent workers actually used after CPU and work-unit caps.
24    pub threads_used: usize,
25    /// Actual worker thread ids that scored the partitions.
26    pub worker_thread_ids: Vec<std::thread::ThreadId>,
27}
28
29/// Ranked candidates and deterministic counters from an extended exact scan.
30#[derive(Clone, Debug, PartialEq)]
31pub struct ScanOutcome {
32    /// Candidates in descending-score, ascending-row-id parity order.
33    pub candidates: Vec<super::ScanCandidate>,
34    /// Deterministic work counters.
35    pub stats: ScanStats,
36    /// Worst score over every scored row, before the top-k cut. Present only
37    /// where the scan visited every allowed row and scored it exactly, which
38    /// is what makes it usable as a normalization anchor.
39    pub worst_score: Option<f32>,
40}
41
42/// Returns the physical performance-core capacity used to cap scan workers.
43///
44/// On Darwin this is `hw.perflevel0.physicalcpu`. Other targets use
45/// [`std::thread::available_parallelism`] as the documented explicit default
46/// because those targets do not expose Darwin performance-level topology.
47///
48/// # Errors
49///
50/// Returns [`ScanError::CpuCount`] when the operating system cannot report a
51/// positive count.
52pub fn physical_thread_capacity() -> Result<usize, ScanError> {
53    static CAPACITY: std::sync::OnceLock<Result<usize, String>> = std::sync::OnceLock::new();
54    match CAPACITY.get_or_init(detect_physical_thread_capacity) {
55        Ok(capacity) => Ok(*capacity),
56        Err(error) => Err(ScanError::CpuCount(error.clone())),
57    }
58}
59
60fn detect_physical_thread_capacity() -> Result<usize, String> {
61    #[cfg(any(target_os = "macos", target_os = "ios"))]
62    {
63        crate::sys::darwin::physical_performance_core_count().map_err(|error| error.to_string())
64    }
65    #[cfg(not(any(target_os = "macos", target_os = "ios")))]
66    {
67        std::thread::available_parallelism()
68            .map(std::num::NonZeroUsize::get)
69            .map_err(|error| error.to_string())
70    }
71}
zeppelin_embed/scan/parallel.rs

zeppelin_embed/scan/
parallel.rs
