kvbm_logical/
lib.rs

1// SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Logical block lifecycle management for KVBM.
5//!
6//! This crate provides the core block lifecycle system:
7//! - Type-safe state transitions (Reset -> Complete -> Registered)
8//! - Block registry with deduplication and attachments
9//! - Active/inactive/reset pool management
10//! - Event pipeline for distributed coordination
11//! - Block manager orchestration
12
13pub mod blocks;
14pub mod events;
15pub mod integrations;
16pub mod manager;
17pub mod metrics;
18pub mod pools;
19pub mod pubsub;
20pub mod registry;
21pub mod sequence;
22pub mod tinylfu;
23
24#[cfg(any(test, feature = "testing"))]
25pub mod testing;
26
27use std::sync::atomic::{AtomicU64, Ordering};
28
29use bincode::{Decode, Encode};
30use serde::{Deserialize, Serialize};
31
32// Re-export common types and traits
33pub use blocks::{
34    BlockError, BlockMetadata, CompleteBlock, ImmutableBlock, LifecyclePin, LifecyclePinRef,
35    MutableBlock, WeakBlock,
36};
37pub use integrations::{
38    ApplyError, DecodeOutcome, NoopDelegate, RequestSequence, SchedulableSequence,
39    SchedulableSequenceBuilder, ScheduleError, SequenceDelegate, SequenceEvent, SequenceState,
40};
41pub use manager::BlockManager;
42pub use registry::BlockRegistry;
43pub use sequence::{
44    BlockSequence, BlockSequenceError, ExternalBlockAssignments, LogicalBlockAssignmentError,
45    LogicalBlockAssignments, zip_assigned, zip_assigned_pending,
46};
47
48pub type BlockId = usize;
49pub type SequenceHash = dynamo_tokens::PositionalLineageHash;
50
51/// Stable, process-unique identifier for a `BlockManager`'s underlying
52/// `BlockStore`.
53///
54/// Generated by an atomic counter at `BlockStore` construction; never
55/// reused. Two [`LifecyclePinRef`]s with the same `ManagerId` come from
56/// the same physical pool; together with [`BlockId`] this disambiguates
57/// a slot's logical address after policy-type erasure (downstream callers
58/// that hold `Arc<dyn LifecyclePin>` lose the manager type parameter but
59/// keep the runtime address).
60///
61/// The reserved value [`ManagerId::NULL`] is never assigned to a real
62/// store — callers may use it as a null/test sentinel.
63#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Encode, Decode, Serialize, Deserialize)]
64pub struct ManagerId(pub u64);
65
66impl ManagerId {
67    /// Sentinel never assigned to a real `BlockStore`.
68    pub const NULL: Self = Self(0);
69
70    /// Allocate the next process-unique `ManagerId`.  Atomic counter,
71    /// `Relaxed` ordering — uniqueness is guaranteed by `fetch_add`,
72    /// happens-before is not needed for an opaque scalar id.
73    pub(crate) fn next() -> Self {
74        static NEXT: AtomicU64 = AtomicU64::new(1);
75        Self(NEXT.fetch_add(1, Ordering::Relaxed))
76    }
77}
78
79pub trait KvbmSequenceHashProvider {
80    fn kvbm_sequence_hash(&self) -> SequenceHash;
81}
82
83impl KvbmSequenceHashProvider for dynamo_tokens::TokenBlock {
84    fn kvbm_sequence_hash(&self) -> SequenceHash {
85        self.positional_lineage_hash()
86    }
87}
88
89/// Logical layout handle type encoding the layout ID.
90///
91/// KVBM manages G1, G2 and G3 layouts directly. G4 is managed by an external service.
92#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Encode, Decode, Serialize, Deserialize)]
93pub enum LogicalLayoutHandle {
94    /// Representation of GPU / Device Memory
95    G1,
96    /// Representation of CPU / Host Memory
97    G2,
98    /// Representation of Disk Storage
99    G3,
100    /// Representation of Blocks held in an external service
101    /// outside the control of the KVBM system.
102    G4,
103}
kvbm_logical/lib.rs

kvbm_logical/
lib.rs
