use std::fmt;
use std::num::NonZeroUsize;
use super::CarrierCount;
const BITS_PER_BITMAP_WORD: usize = u64::BITS as usize;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(super) enum GeometryError {
ZeroPageSize,
ZeroBlockSize,
ZeroCarrierSize,
CarrierNotPageMultiple {
carrier_size: usize,
page_size: usize,
},
BlockNotCarrierMultiple {
block_size: usize,
carrier_size: usize,
},
CarrierIndexOverflow {
carriers_per_block: usize,
},
ZeroByteRequest,
}
impl fmt::Display for GeometryError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::ZeroPageSize => f.write_str("page size must be nonzero"),
Self::ZeroBlockSize => f.write_str("block size must be nonzero"),
Self::ZeroCarrierSize => f.write_str("carrier size must be nonzero"),
Self::CarrierNotPageMultiple {
carrier_size,
page_size,
} => write!(
f,
"carrier size {carrier_size} is not a multiple of page size {page_size}"
),
Self::BlockNotCarrierMultiple {
block_size,
carrier_size,
} => write!(
f,
"block size {block_size} is not a multiple of carrier size {carrier_size}"
),
Self::CarrierIndexOverflow { carriers_per_block } => write!(
f,
"block carrier count {carriers_per_block} exceeds the carrier index range"
),
Self::ZeroByteRequest => f.write_str("a carrier request must be nonzero"),
}
}
}
impl std::error::Error for GeometryError {}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(super) struct PoolGeometry {
page_size: NonZeroUsize,
block_size: NonZeroUsize,
carrier_size: NonZeroUsize,
carriers_per_block: NonZeroUsize,
bitmap_words: NonZeroUsize,
final_word_mask: u64,
}
impl PoolGeometry {
pub(super) fn new(
page_size: usize,
block_size: usize,
carrier_size: usize,
) -> Result<Self, GeometryError> {
let page_size = NonZeroUsize::new(page_size).ok_or(GeometryError::ZeroPageSize)?;
let block_size = NonZeroUsize::new(block_size).ok_or(GeometryError::ZeroBlockSize)?;
let carrier_size = NonZeroUsize::new(carrier_size).ok_or(GeometryError::ZeroCarrierSize)?;
if !carrier_size.get().is_multiple_of(page_size.get()) {
return Err(GeometryError::CarrierNotPageMultiple {
carrier_size: carrier_size.get(),
page_size: page_size.get(),
});
}
if !block_size.get().is_multiple_of(carrier_size.get()) {
return Err(GeometryError::BlockNotCarrierMultiple {
block_size: block_size.get(),
carrier_size: carrier_size.get(),
});
}
let carriers_per_block = NonZeroUsize::new(block_size.get() / carrier_size)
.expect("a nonzero whole-carrier block contains a carrier");
u32::try_from(carriers_per_block.get() - 1).map_err(|_| {
GeometryError::CarrierIndexOverflow {
carriers_per_block: carriers_per_block.get(),
}
})?;
let bitmap_words =
NonZeroUsize::new(carriers_per_block.get().div_ceil(BITS_PER_BITMAP_WORD))
.expect("a nonzero carrier count requires a bitmap word");
let final_bits = carriers_per_block.get() % BITS_PER_BITMAP_WORD;
let final_word_mask = if final_bits == 0 {
u64::MAX
} else {
(1u64 << final_bits) - 1
};
Ok(Self {
page_size,
block_size,
carrier_size,
carriers_per_block,
bitmap_words,
final_word_mask,
})
}
pub(super) fn page_size(self) -> usize {
self.page_size.get()
}
pub(super) fn block_size(self) -> usize {
self.block_size.get()
}
pub(super) fn carrier_size(self) -> usize {
self.carrier_size.get()
}
pub(super) fn carriers_per_block(self) -> CarrierCount {
CarrierCount::new(self.carriers_per_block.get())
}
pub(super) fn bitmap_words(self) -> usize {
self.bitmap_words.get()
}
pub(super) fn final_word_mask(self) -> u64 {
self.final_word_mask
}
pub(super) fn bitmap_word_mask(self, word_index: usize) -> Option<u64> {
if word_index >= self.bitmap_words() {
return None;
}
if word_index + 1 == self.bitmap_words() {
Some(self.final_word_mask())
} else {
Some(u64::MAX)
}
}
pub(super) fn carriers_for_bytes(self, bytes: usize) -> Result<CarrierCount, GeometryError> {
if bytes == 0 {
return Err(GeometryError::ZeroByteRequest);
}
let count = bytes.div_ceil(self.carrier_size.get());
Ok(CarrierCount::new(count))
}
pub(super) fn carrier_offset(self, index: usize) -> Option<usize> {
if index >= self.carriers_per_block.get() {
return None;
}
index.checked_mul(self.carrier_size.get())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn rejects_invalid_dimensions() {
assert_eq!(
PoolGeometry::new(0, 4096, 4096),
Err(GeometryError::ZeroPageSize)
);
assert_eq!(
PoolGeometry::new(4096, 0, 4096),
Err(GeometryError::ZeroBlockSize)
);
assert_eq!(
PoolGeometry::new(4096, 4096, 0),
Err(GeometryError::ZeroCarrierSize)
);
assert_eq!(
PoolGeometry::new(4096, 12288, 6144),
Err(GeometryError::CarrierNotPageMultiple {
carrier_size: 6144,
page_size: 4096,
})
);
assert_eq!(
PoolGeometry::new(4096, 12288, 8192),
Err(GeometryError::BlockNotCarrierMultiple {
block_size: 12288,
carrier_size: 8192,
})
);
assert_eq!(
PoolGeometry::new(4096, 4096, 8192),
Err(GeometryError::BlockNotCarrierMultiple {
block_size: 4096,
carrier_size: 8192,
})
);
}
#[cfg(target_pointer_width = "64")]
#[test]
fn rejects_carrier_index_overflow() {
let carriers_per_block = u32::MAX as usize + 2;
assert_eq!(
PoolGeometry::new(1, carriers_per_block, 1),
Err(GeometryError::CarrierIndexOverflow { carriers_per_block })
);
}
#[test]
fn rounds_byte_requests_to_carriers() {
let geometry = PoolGeometry::new(4096, 8192 * 8, 8192).unwrap();
assert_eq!(
geometry.carriers_for_bytes(1).unwrap(),
CarrierCount::new(1)
);
assert_eq!(
geometry.carriers_for_bytes(8192).unwrap(),
CarrierCount::new(1)
);
assert_eq!(
geometry.carriers_for_bytes(8193).unwrap(),
CarrierCount::new(2)
);
assert_eq!(
geometry.carriers_for_bytes(0),
Err(GeometryError::ZeroByteRequest)
);
assert_eq!(
geometry.carriers_for_bytes(usize::MAX).unwrap(),
CarrierCount::new((usize::MAX - 1) / 8192 + 1)
);
}
#[test]
fn computes_checked_carrier_offsets() {
let geometry = PoolGeometry::new(4096, 8192 * 3, 8192).unwrap();
assert_eq!(geometry.carrier_offset(0), Some(0));
assert_eq!(geometry.carrier_offset(2), Some(16384));
assert_eq!(geometry.carrier_offset(3), None);
}
#[test]
fn masks_every_partial_bitmap_width() {
for carriers in 1..=BITS_PER_BITMAP_WORD * 3 {
let geometry = PoolGeometry::new(1, carriers, 1).unwrap();
let valid = (0..geometry.bitmap_words())
.map(|word_index| {
let mask = geometry.bitmap_word_mask(word_index).unwrap();
let expected = if word_index + 1 == geometry.bitmap_words() {
geometry.final_word_mask()
} else {
u64::MAX
};
assert_eq!(mask, expected);
mask.count_ones() as usize
})
.sum::<usize>();
assert_eq!(
geometry.bitmap_words(),
carriers.div_ceil(BITS_PER_BITMAP_WORD)
);
assert_eq!(valid, carriers);
assert_eq!(geometry.bitmap_word_mask(geometry.bitmap_words()), None);
}
}
#[test]
fn masks_a_seventy_carrier_block() {
let geometry = PoolGeometry::new(1, 70, 1).unwrap();
assert_eq!(geometry.bitmap_words(), 2);
assert_eq!(geometry.final_word_mask(), 0b11_1111);
}
#[test]
fn full_final_word_uses_every_bit() {
let geometry = PoolGeometry::new(1, 128, 1).unwrap();
assert_eq!(geometry.bitmap_words(), 2);
assert_eq!(geometry.final_word_mask(), u64::MAX);
}
#[test]
fn exposes_validated_dimensions() {
let geometry = PoolGeometry::new(4096, 8192 * 65, 8192).unwrap();
assert_eq!(geometry.page_size(), 4096);
assert_eq!(geometry.block_size(), 8192 * 65);
assert_eq!(geometry.carrier_size(), 8192);
assert_eq!(geometry.carriers_per_block(), CarrierCount::new(65));
assert_eq!(geometry.bitmap_words(), 2);
assert_eq!(geometry.final_word_mask(), 1);
}
}