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 bincode::{Decode, Encode};
28use serde::{Deserialize, Serialize};
29
30// Re-export common types and traits
31pub use blocks::{
32    BlockError, BlockMetadata, CompleteBlock, ImmutableBlock, MutableBlock, WeakBlock,
33};
34pub use integrations::{
35    ApplyError, DecodeOutcome, NoopDelegate, RequestSequence, SchedulableSequence,
36    SchedulableSequenceBuilder, ScheduleError, SequenceDelegate, SequenceEvent, SequenceState,
37};
38pub use manager::BlockManager;
39pub use registry::BlockRegistry;
40pub use sequence::{
41    BlockSequence, BlockSequenceError, ExternalBlockAssignments, LogicalBlockAssignmentError,
42    LogicalBlockAssignments, zip_assigned, zip_assigned_pending,
43};
44
45pub type BlockId = usize;
46pub type SequenceHash = dynamo_tokens::PositionalLineageHash;
47
48pub trait KvbmSequenceHashProvider {
49    fn kvbm_sequence_hash(&self) -> SequenceHash;
50}
51
52impl KvbmSequenceHashProvider for dynamo_tokens::TokenBlock {
53    fn kvbm_sequence_hash(&self) -> SequenceHash {
54        self.positional_lineage_hash()
55    }
56}
57
58/// Logical layout handle type encoding the layout ID.
59///
60/// KVBM manages G1, G2 and G3 layouts directly. G4 is managed by an external service.
61#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Encode, Decode, Serialize, Deserialize)]
62pub enum LogicalLayoutHandle {
63    /// Representation of GPU / Device Memory
64    G1,
65    /// Representation of CPU / Host Memory
66    G2,
67    /// Representation of Disk Storage
68    G3,
69    /// Representation of Blocks held in an external service
70    /// outside the control of the KVBM system.
71    G4,
72}
kvbm_logical/lib.rs

kvbm_logical/
lib.rs
