use std::sync::LazyLock;
pub const FALLBACK_L1_BYTES: usize = 32 * 1024;
pub const FALLBACK_L2_BYTES: usize = 256 * 1024;
pub const FALLBACK_L3_BYTES: usize = 8 * 1024 * 1024;
pub const FALLBACK_CACHE_LINE_BYTES: usize = 64;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct CacheGeometry {
l1_bytes: usize,
l2_bytes: usize,
l3_bytes: usize,
cache_line_bytes: usize,
}
impl CacheGeometry {
#[must_use]
pub const fn fallback() -> Self {
Self {
l1_bytes: FALLBACK_L1_BYTES,
l2_bytes: FALLBACK_L2_BYTES,
l3_bytes: FALLBACK_L3_BYTES,
cache_line_bytes: FALLBACK_CACHE_LINE_BYTES,
}
}
#[must_use]
pub const fn with_cache_line_bytes(cache_line_bytes: usize) -> Option<Self> {
if cache_line_bytes == 0 {
return None;
}
let fallback = Self::fallback();
Some(Self {
cache_line_bytes,
..fallback
})
}
#[must_use]
pub fn detect() -> Self {
detect_cache_geometry()
}
#[must_use]
pub const fn l1_bytes(self) -> usize {
self.l1_bytes
}
#[must_use]
pub const fn l2_bytes(self) -> usize {
self.l2_bytes
}
#[must_use]
pub const fn l3_bytes(self) -> usize {
self.l3_bytes
}
#[must_use]
pub const fn cache_line_bytes(self) -> usize {
self.cache_line_bytes
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct MatmulTilePolicy {
row_block: usize,
}
impl MatmulTilePolicy {
#[must_use]
pub const fn fixed(row_block: usize) -> Option<Self> {
match row_block {
1 | 2 | 4 | 8 | 16 | 32 => Some(Self { row_block }),
_ => None,
}
}
#[must_use]
pub fn automatic(element_bytes: usize, cols: usize) -> Self {
Self::for_geometry(cached_cache_geometry(), element_bytes, cols)
}
#[must_use]
pub fn for_geometry(geometry: CacheGeometry, element_bytes: usize, cols: usize) -> Self {
let row_bytes = cols.saturating_mul(element_bytes.max(1));
if row_bytes == 0 {
return Self { row_block: 1 };
}
let budget = geometry.l2_bytes() / 4;
let capacity = (budget / row_bytes).clamp(1, 32);
let row_block = if capacity >= 32 {
32
} else {
let next_power = capacity.next_power_of_two();
if next_power == capacity {
capacity
} else {
next_power / 2
}
}
.max(1);
Self { row_block }
}
#[must_use]
pub const fn row_block(self) -> usize {
self.row_block
}
}
#[must_use]
pub fn cache_geometry() -> CacheGeometry {
CacheGeometry::detect()
}
#[must_use]
pub fn cached_cache_geometry() -> CacheGeometry {
static GEOMETRY: LazyLock<CacheGeometry> = LazyLock::new(CacheGeometry::detect);
*GEOMETRY
}
#[must_use]
#[inline]
pub fn working_set_spills_llc(bytes: usize) -> bool {
bytes > cached_cache_geometry().l3_bytes()
}
#[must_use]
#[inline]
pub fn working_set_spills_llc_for_geometry(geometry: CacheGeometry, bytes: usize) -> bool {
bytes > geometry.l3_bytes()
}
#[cfg(feature = "topology")]
fn detect_cache_geometry() -> CacheGeometry {
let Some(topology) = themis::CpuTopology::detect() else {
return CacheGeometry::fallback();
};
geometry_from_cache_levels(topology.cache_levels().unwrap_or(&[]))
}
#[cfg(not(feature = "topology"))]
fn detect_cache_geometry() -> CacheGeometry {
CacheGeometry::fallback()
}
#[cfg(feature = "topology")]
fn geometry_from_cache_levels(levels: &[themis::CacheLevel]) -> CacheGeometry {
let mut geometry = CacheGeometry::fallback();
let mut reported_line_bytes: Option<usize> = None;
let mut reported: [Option<usize>; 3] = [None; 3];
for level in levels {
let slot = level
.level
.checked_sub(1)
.and_then(|index| usize::try_from(index).ok())
.and_then(|index| reported.get_mut(index));
if let Some(slot) = slot.filter(|_| level.size_bytes > 0) {
*slot = Some(slot.map_or(level.size_bytes, |smallest| smallest.min(level.size_bytes)));
}
if let Some(line) = level.line_bytes.filter(|&line| line > 0) {
reported_line_bytes = Some(reported_line_bytes.map_or(line, |widest| line.max(widest)));
}
}
if let Some(l1) = reported[0] {
geometry.l1_bytes = l1;
}
if let Some(l2) = reported[1] {
geometry.l2_bytes = l2;
}
if let Some(l3) = reported[2] {
geometry.l3_bytes = l3;
}
geometry.cache_line_bytes = reported_line_bytes.unwrap_or(FALLBACK_CACHE_LINE_BYTES);
geometry
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn fallback_geometry_is_conservative() {
let geometry = CacheGeometry::fallback();
assert_eq!(geometry.l1_bytes(), 32 * 1024);
assert_eq!(geometry.l2_bytes(), 256 * 1024);
assert_eq!(geometry.l3_bytes(), 8 * 1024 * 1024);
assert_eq!(geometry.cache_line_bytes(), 64);
}
#[test]
fn explicit_line_geometry_requires_a_positive_width() {
assert_eq!(CacheGeometry::with_cache_line_bytes(0), None);
let geometry = CacheGeometry::with_cache_line_bytes(128)
.expect("positive cache-line width is a valid explicit policy");
assert_eq!(geometry.cache_line_bytes(), 128);
assert_eq!(geometry.l1_bytes(), FALLBACK_L1_BYTES);
assert_eq!(geometry.l2_bytes(), FALLBACK_L2_BYTES);
assert_eq!(geometry.l3_bytes(), FALLBACK_L3_BYTES);
}
#[test]
fn matmul_policy_preserves_measured_default_for_common_shapes() {
let geometry = CacheGeometry::fallback();
assert_eq!(
MatmulTilePolicy::for_geometry(geometry, 8, 64).row_block(),
32
);
assert_eq!(
MatmulTilePolicy::for_geometry(geometry, 8, 256).row_block(),
32
);
}
#[test]
fn matmul_policy_downsizes_wide_rows_without_exceeding_bounds() {
let geometry = CacheGeometry::fallback();
assert_eq!(
MatmulTilePolicy::for_geometry(geometry, 8, 1_024).row_block(),
8
);
assert_eq!(
MatmulTilePolicy::for_geometry(geometry, 8, 2_048).row_block(),
4
);
assert_eq!(
MatmulTilePolicy::for_geometry(geometry, 8, 1).row_block(),
32
);
}
#[test]
fn fixed_matmul_policy_accepts_only_supported_specializations() {
assert_eq!(
MatmulTilePolicy::fixed(32).map(MatmulTilePolicy::row_block),
Some(32)
);
assert_eq!(MatmulTilePolicy::fixed(3), None);
assert_eq!(MatmulTilePolicy::fixed(64), None);
}
#[test]
fn matmul_policy_handles_empty_and_tiny_cache_inputs() {
assert_eq!(
MatmulTilePolicy::for_geometry(CacheGeometry::fallback(), 0, 0).row_block(),
1
);
let tiny = CacheGeometry {
l1_bytes: 4 * 1024,
l2_bytes: 32 * 1024,
l3_bytes: 256 * 1024,
cache_line_bytes: 64,
};
assert_eq!(MatmulTilePolicy::for_geometry(tiny, 8, 256).row_block(), 4);
}
#[cfg(feature = "topology")]
fn cache_level(level: u32, size_bytes: usize, line_bytes: Option<usize>) -> themis::CacheLevel {
themis::CacheLevel {
level,
size_bytes,
line_bytes,
shared_processors: [0, 1].into(),
}
}
#[cfg(feature = "topology")]
#[test]
fn heterogeneous_levels_resolve_to_the_smallest_reported_capacity() {
let levels = [
cache_level(1, 32 * 1024, Some(64)),
cache_level(2, 3 * 1024 * 1024, Some(64)),
cache_level(1, 48 * 1024, Some(64)),
cache_level(2, 4 * 1024 * 1024, Some(64)),
cache_level(3, 36 * 1024 * 1024, Some(64)),
];
let geometry = geometry_from_cache_levels(&levels);
assert_eq!(geometry.l1_bytes(), 32 * 1024);
assert_eq!(geometry.l2_bytes(), 3 * 1024 * 1024);
assert_eq!(geometry.l3_bytes(), 36 * 1024 * 1024);
}
#[cfg(feature = "topology")]
#[test]
fn a_reported_capacity_is_never_clamped_to_the_fallback() {
let levels = [cache_level(2, 3 * 1024 * 1024, Some(64))];
let geometry = geometry_from_cache_levels(&levels);
assert_eq!(geometry.l2_bytes(), 3 * 1024 * 1024);
assert_eq!(geometry.l1_bytes(), CacheGeometry::fallback().l1_bytes());
assert_eq!(geometry.l3_bytes(), CacheGeometry::fallback().l3_bytes());
}
#[cfg(feature = "topology")]
#[test]
fn cache_levels_override_capacities_and_line_width() {
let levels = [
cache_level(1, 48 * 1024, Some(128)),
cache_level(2, 1024 * 1024, Some(128)),
cache_level(3, 32 * 1024 * 1024, Some(128)),
];
let geometry = geometry_from_cache_levels(&levels);
assert_eq!(geometry.l1_bytes(), 48 * 1024);
assert_eq!(geometry.l2_bytes(), 1024 * 1024);
assert_eq!(geometry.l3_bytes(), 32 * 1024 * 1024);
assert_eq!(geometry.cache_line_bytes(), 128);
}
#[cfg(feature = "topology")]
#[test]
fn widest_reported_line_width_wins_across_levels() {
let levels = [
cache_level(1, 64 * 1024, Some(64)),
cache_level(2, 4 * 1024 * 1024, None),
cache_level(4, 128 * 1024 * 1024, Some(128)),
];
let geometry = geometry_from_cache_levels(&levels);
assert_eq!(geometry.cache_line_bytes(), 128);
assert_eq!(geometry.l1_bytes(), 64 * 1024);
assert_eq!(geometry.l2_bytes(), 4 * 1024 * 1024);
}
#[cfg(feature = "topology")]
#[test]
fn reported_line_width_narrower_than_the_fallback_is_honoured() {
let levels = [cache_level(1, 16 * 1024, Some(32))];
let geometry = geometry_from_cache_levels(&levels);
assert_eq!(geometry.cache_line_bytes(), 32);
}
#[cfg(feature = "topology")]
#[test]
fn zero_sized_or_unknown_cache_levels_keep_fallbacks() {
let levels = [
cache_level(1, 0, Some(0)),
cache_level(4, 128 * 1024 * 1024, None),
];
let geometry = geometry_from_cache_levels(&levels);
assert_eq!(geometry, CacheGeometry::fallback());
assert_eq!(geometry.cache_line_bytes(), FALLBACK_CACHE_LINE_BYTES);
}
}