lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

visibility_index.rs (3988B)


      1 //! Bounded canonical visibility-index preparation contracts.
      2 
      3 use super::EventSourceToken;
      4 use crate::Error;
      5 
      6 /// Validated logical work envelope for one canonical index preparation call.
      7 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
      8 pub struct VisibilityIndexBounds {
      9     rows: u16,
     10     bytes: u64,
     11 }
     12 
     13 impl VisibilityIndexBounds {
     14     /// Validates 1..=64 source rows and 1..=16 MiB of logical allocation charge.
     15     pub fn new(rows: u16, bytes: u64) -> Result<Self, Error> {
     16         if rows == 0 || rows > 64 || bytes == 0 || bytes > 16 * 1024 * 1024 {
     17             return Err(Error::InvalidVisibilityIndexBounds);
     18         }
     19         Ok(Self { rows, bytes })
     20     }
     21 
     22     /// Maximum source rows materialized in this call.
     23     pub const fn rows(self) -> u16 {
     24         self.rows
     25     }
     26 
     27     /// Maximum conservative logical allocation charge in this call.
     28     pub const fn bytes(self) -> u64 {
     29         self.bytes
     30     }
     31 
     32     /// Charges retained bytes, decoded variable data and derived metadata.
     33     ///
     34     /// This conservative envelope is not a measurement of allocator RSS.
     35     #[doc(hidden)]
     36     pub fn charge(signed_bytes: u64) -> Result<u64, Error> {
     37         signed_bytes
     38             .checked_mul(16)
     39             .and_then(|value| value.checked_add(4096))
     40             .ok_or(Error::SpaceInsufficient)
     41     }
     42 }
     43 
     44 /// Durable progress observed after one canonical index preparation transaction.
     45 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
     46 pub struct VisibilityIndexProgress {
     47     token: EventSourceToken,
     48     source_sequence: u64,
     49     replay_epoch: u64,
     50     processed_rows: u16,
     51     processed_keys: u16,
     52     charged_bytes: u64,
     53     complete: bool,
     54 }
     55 
     56 impl VisibilityIndexProgress {
     57     #[doc(hidden)]
     58     pub const fn new(
     59         token: EventSourceToken,
     60         source_sequence: u64,
     61         replay_epoch: u64,
     62         processed_rows: u16,
     63         charged_bytes: u64,
     64         complete: bool,
     65     ) -> Self {
     66         Self {
     67             token,
     68             source_sequence,
     69             replay_epoch,
     70             processed_rows,
     71             processed_keys: 0,
     72             charged_bytes,
     73             complete,
     74         }
     75     }
     76 
     77     /// Source fence read inside the completed preparation transaction.
     78     pub const fn token(self) -> EventSourceToken {
     79         self.token
     80     }
     81     /// Last initial-backfill sequence durably prepared; it never restarts on admission.
     82     pub const fn source_sequence(self) -> u64 {
     83         self.source_sequence
     84     }
     85     /// Last durable changed-event replay epoch.
     86     pub const fn replay_epoch(self) -> u64 {
     87         self.replay_epoch
     88     }
     89     /// Actual source rows materialized, including repeated changed rows.
     90     pub const fn processed_rows(self) -> u16 {
     91         self.processed_rows
     92     }
     93     /// Affected deletion keys refreshed within the same total row-unit budget.
     94     pub const fn processed_keys(self) -> u16 {
     95         self.processed_keys
     96     }
     97 
     98     #[doc(hidden)]
     99     pub const fn with_processed_keys(mut self, keys: u16) -> Self {
    100         self.processed_keys = keys;
    101         self
    102     }
    103     /// Conservative logical allocation charge of this call.
    104     pub const fn charged_bytes(self) -> u64 {
    105         self.charged_bytes
    106     }
    107     /// Whether canonical metadata matches `token`; it is not a consumer-content claim.
    108     pub const fn is_complete(self) -> bool {
    109         self.complete
    110     }
    111 }
    112 
    113 #[cfg(test)]
    114 mod tests {
    115     use super::*;
    116 
    117     #[test]
    118     fn work_envelope_rejects_zero_and_one_over_without_relaxing_caps() {
    119         assert!(VisibilityIndexBounds::new(64, 16 * 1024 * 1024).is_ok());
    120         for (rows, bytes) in [(0, 1), (65, 1), (1, 0), (1, 16 * 1024 * 1024 + 1)] {
    121             assert_eq!(
    122                 VisibilityIndexBounds::new(rows, bytes),
    123                 Err(Error::InvalidVisibilityIndexBounds)
    124             );
    125         }
    126         assert_eq!(VisibilityIndexBounds::charge(10).unwrap(), 4256);
    127         assert_eq!(
    128             VisibilityIndexBounds::charge(u64::MAX),
    129             Err(Error::SpaceInsufficient)
    130         );
    131     }
    132 }