use std::sync::atomic::{AtomicU32, AtomicU64};
use crate::format::{
COORD_CACHE_LINE, COORD_CHECKPOINTER_SLOT_OFFSET, COORD_MAGIC, COORD_READER_SLOT_COUNT,
COORD_READER_SLOTS_OFFSET, COORD_REGION_OFFSET, COORD_REGION_SIZE, COORD_VERSION,
COORD_WRITER_SLOT_OFFSET,
};
pub(crate) const COORD_HEADER_SIZE: usize = 64;
pub(crate) const COORD_WRITER_SLOT_SIZE: usize = 64;
pub(crate) const COORD_CHECKPOINTER_SLOT_SIZE: usize = 64;
pub(crate) const COORD_READER_SLOT_SIZE: usize = 64;
const _: () = {
assert!(COORD_HEADER_SIZE == COORD_CACHE_LINE);
assert!(COORD_WRITER_SLOT_SIZE == COORD_CACHE_LINE);
assert!(COORD_CHECKPOINTER_SLOT_SIZE == COORD_CACHE_LINE);
assert!(COORD_READER_SLOT_SIZE == COORD_CACHE_LINE);
assert!(COORD_WRITER_SLOT_OFFSET == COORD_HEADER_SIZE);
assert!(COORD_CHECKPOINTER_SLOT_OFFSET == COORD_WRITER_SLOT_OFFSET + COORD_WRITER_SLOT_SIZE);
assert!(
COORD_READER_SLOTS_OFFSET == COORD_CHECKPOINTER_SLOT_OFFSET + COORD_CHECKPOINTER_SLOT_SIZE
);
let total =
COORD_READER_SLOTS_OFFSET + COORD_READER_SLOT_COUNT as usize * COORD_READER_SLOT_SIZE;
assert!(total == COORD_REGION_SIZE);
};
pub(crate) mod header_offset {
pub(crate) const MAGIC: usize = 0;
pub(crate) const VERSION: usize = 8;
pub(crate) const READER_SLOT_COUNT: usize = 12;
pub(crate) const PUBLISHED_TOC_OFFSET: usize = 16;
pub(crate) const PUBLISHED_SNAPSHOT_GENERATION: usize = 24;
}
#[allow(
dead_code,
reason = "Stage 3b consumers — OWNER_* are stamped at slot acquire"
)]
pub(crate) mod reader_slot_offset {
pub(crate) const PINNED_TOC_OFFSET: usize = 0;
pub(crate) const PINNED_SNAPSHOT_GENERATION: usize = 8;
pub(crate) const OWNER_PID: usize = 16;
pub(crate) const OWNER_INSTANCE: usize = 20;
}
pub(crate) fn stamp_initial(header_buf: &mut [u8]) {
debug_assert!(header_buf.len() >= COORD_REGION_OFFSET + COORD_REGION_SIZE);
let region = &mut header_buf[COORD_REGION_OFFSET..COORD_REGION_OFFSET + COORD_REGION_SIZE];
region.fill(0);
region[header_offset::MAGIC..header_offset::MAGIC + 8].copy_from_slice(&COORD_MAGIC);
region[header_offset::VERSION..header_offset::VERSION + 4]
.copy_from_slice(&COORD_VERSION.to_le_bytes());
region[header_offset::READER_SLOT_COUNT..header_offset::READER_SLOT_COUNT + 4]
.copy_from_slice(&COORD_READER_SLOT_COUNT.to_le_bytes());
for n in 0..COORD_READER_SLOT_COUNT as usize {
let slot_start = COORD_READER_SLOTS_OFFSET + n * COORD_READER_SLOT_SIZE;
let pinned_off = slot_start + reader_slot_offset::PINNED_TOC_OFFSET;
region[pinned_off..pinned_off + 8].copy_from_slice(&u64::MAX.to_le_bytes());
}
}
#[allow(
dead_code,
reason = "Stage 3b consumers use this for open-time coord region detection"
)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) struct CoordinationHeaderView {
pub(crate) magic: [u8; 8],
pub(crate) version: u32,
pub(crate) reader_slot_count: u32,
pub(crate) published_toc_offset: u64,
pub(crate) published_snapshot_generation: u64,
}
impl CoordinationHeaderView {
#[allow(
dead_code,
reason = "Stage 3b open path uses this for region detection"
)]
pub(crate) fn is_valid(&self) -> bool {
self.magic == COORD_MAGIC && self.version == COORD_VERSION
}
}
#[allow(dead_code, reason = "Stage 3b open path consumes this")]
pub(crate) fn read_header_view(header_buf: &[u8]) -> Option<CoordinationHeaderView> {
if header_buf.len() < COORD_REGION_OFFSET + COORD_HEADER_SIZE {
return None;
}
let region = &header_buf[COORD_REGION_OFFSET..COORD_REGION_OFFSET + COORD_HEADER_SIZE];
let mut magic = [0u8; 8];
magic.copy_from_slice(®ion[header_offset::MAGIC..header_offset::MAGIC + 8]);
let version = u32::from_le_bytes(
region[header_offset::VERSION..header_offset::VERSION + 4]
.try_into()
.expect("4 bytes"),
);
let reader_slot_count = u32::from_le_bytes(
region[header_offset::READER_SLOT_COUNT..header_offset::READER_SLOT_COUNT + 4]
.try_into()
.expect("4 bytes"),
);
let published_toc_offset = u64::from_le_bytes(
region[header_offset::PUBLISHED_TOC_OFFSET..header_offset::PUBLISHED_TOC_OFFSET + 8]
.try_into()
.expect("8 bytes"),
);
let published_snapshot_generation = u64::from_le_bytes(
region[header_offset::PUBLISHED_SNAPSHOT_GENERATION
..header_offset::PUBLISHED_SNAPSHOT_GENERATION + 8]
.try_into()
.expect("8 bytes"),
);
Some(CoordinationHeaderView {
magic,
version,
reader_slot_count,
published_toc_offset,
published_snapshot_generation,
})
}
unsafe fn atomic_u64(region: &[u8], offset: usize) -> &AtomicU64 {
debug_assert!(offset + 8 <= region.len());
debug_assert!(
offset.is_multiple_of(8),
"AtomicU64 requires 8-byte alignment"
);
unsafe { &*(region.as_ptr().add(offset) as *const AtomicU64) }
}
#[allow(dead_code, reason = "consumed by reader-slot owner stamping")]
unsafe fn atomic_u32(region: &[u8], offset: usize) -> &AtomicU32 {
debug_assert!(offset + 4 <= region.len());
debug_assert!(
offset.is_multiple_of(4),
"AtomicU32 requires 4-byte alignment"
);
unsafe { &*(region.as_ptr().add(offset) as *const AtomicU32) }
}
pub(crate) fn region_slice(mmap: &memmap2::Mmap) -> Option<&[u8]> {
if mmap.len() < COORD_REGION_OFFSET + COORD_REGION_SIZE {
return None;
}
Some(&mmap[COORD_REGION_OFFSET..COORD_REGION_OFFSET + COORD_REGION_SIZE])
}
#[allow(
dead_code,
reason = "Stage 3b writes via pwrite; readers may use this for atomic load"
)]
pub(crate) unsafe fn published_toc_offset(region: &[u8]) -> &AtomicU64 {
unsafe { atomic_u64(region, header_offset::PUBLISHED_TOC_OFFSET) }
}
pub(crate) unsafe fn published_snapshot_generation(region: &[u8]) -> &AtomicU64 {
unsafe { atomic_u64(region, header_offset::PUBLISHED_SNAPSHOT_GENERATION) }
}
pub(crate) fn is_active(region: &[u8]) -> bool {
if region.len() < COORD_HEADER_SIZE {
return false;
}
if region[header_offset::MAGIC..header_offset::MAGIC + 8] != COORD_MAGIC {
return false;
}
let version = u32::from_le_bytes(
region[header_offset::VERSION..header_offset::VERSION + 4]
.try_into()
.expect("4 bytes"),
);
version == COORD_VERSION
}
#[allow(dead_code, reason = "consumed by reader-slot pin (Stage 4)")]
pub(crate) struct ReaderSlot<'r> {
region: &'r [u8],
base: usize,
}
#[allow(dead_code, reason = "consumed by reader-slot pin (Stage 4)")]
impl<'r> ReaderSlot<'r> {
pub(crate) fn nth(region: &'r [u8], n: usize) -> Option<Self> {
let base = COORD_READER_SLOTS_OFFSET + n * COORD_READER_SLOT_SIZE;
if base + COORD_READER_SLOT_SIZE > region.len() {
return None;
}
Some(Self { region, base })
}
pub(crate) fn pinned_toc_offset(&self) -> &AtomicU64 {
unsafe {
atomic_u64(
self.region,
self.base + reader_slot_offset::PINNED_TOC_OFFSET,
)
}
}
pub(crate) fn pinned_snapshot_generation(&self) -> &AtomicU64 {
unsafe {
atomic_u64(
self.region,
self.base + reader_slot_offset::PINNED_SNAPSHOT_GENERATION,
)
}
}
pub(crate) fn owner_pid(&self) -> &AtomicU32 {
unsafe { atomic_u32(self.region, self.base + reader_slot_offset::OWNER_PID) }
}
pub(crate) fn owner_instance(&self) -> &AtomicU32 {
unsafe { atomic_u32(self.region, self.base + reader_slot_offset::OWNER_INSTANCE) }
}
pub(crate) fn lock_byte_in_file(slot_index: usize) -> u64 {
(COORD_REGION_OFFSET + COORD_READER_SLOTS_OFFSET + slot_index * COORD_READER_SLOT_SIZE)
as u64
}
}
pub(crate) const WRITER_LOCK_BYTE: u64 = (COORD_REGION_OFFSET + COORD_WRITER_SLOT_OFFSET) as u64;
#[cfg(test)]
mod tests {
use super::*;
use crate::format::HEADER_SIZE;
#[test]
fn stamp_initial_round_trips() {
let mut buf = vec![0u8; HEADER_SIZE];
stamp_initial(&mut buf);
let view = read_header_view(&buf).expect("decode");
assert!(view.is_valid());
assert_eq!(view.magic, COORD_MAGIC);
assert_eq!(view.version, COORD_VERSION);
assert_eq!(view.reader_slot_count, COORD_READER_SLOT_COUNT);
assert_eq!(view.published_toc_offset, 0);
assert_eq!(view.published_snapshot_generation, 0);
}
#[test]
fn untouched_buffer_does_not_validate() {
let buf = vec![0u8; HEADER_SIZE];
let view = read_header_view(&buf).expect("decode");
assert!(!view.is_valid(), "all-zero magic must not validate");
}
#[test]
fn reader_slots_initialize_to_free_sentinel() {
let mut buf = vec![0u8; HEADER_SIZE];
stamp_initial(&mut buf);
for n in 0..COORD_READER_SLOT_COUNT as usize {
let slot_start =
COORD_REGION_OFFSET + COORD_READER_SLOTS_OFFSET + n * COORD_READER_SLOT_SIZE;
let pinned_off = slot_start + reader_slot_offset::PINNED_TOC_OFFSET;
let val = u64::from_le_bytes(buf[pinned_off..pinned_off + 8].try_into().unwrap());
assert_eq!(
val,
u64::MAX,
"reader slot {n} must initialize to u64::MAX (free sentinel)"
);
}
}
#[test]
fn region_does_not_overflow_header() {
const {
assert!(COORD_REGION_OFFSET + COORD_REGION_SIZE <= HEADER_SIZE);
}
}
}