aimdb_core/buffer/
mod.rs

1//! Runtime-agnostic buffer traits and configuration for async producer-consumer dispatch
2//!
3//! This module defines the buffer abstraction without runtime-specific implementations.
4//! Actual buffer implementations are provided by adapter crates:
5//! - `aimdb-tokio-adapter` - Tokio-based buffers (std environments)
6//! - `aimdb-embassy-adapter` - Embassy-based buffers (embedded no_std)
7//!
8//! # Buffer Types
9//!
10//! Three buffering strategies are supported:
11//! - **SPMC Ring**: Bounded backlog with per-consumer lag tolerance
12//! - **SingleLatest**: Only newest value kept (no backlog)
13//! - **Mailbox**: Single-slot with overwrite semantics
14//!
15//! # Design Philosophy
16//!
17//! Each record type can choose the appropriate buffer based on its data flow:
18//! - High-frequency telemetry → SPMC ring
19//! - Configuration state → SingleLatest
20//! - Commands/triggers → Mailbox
21//!
22//! # Architecture
23//!
24//! ```text
25//! ┌─────────────────────────────────────────────────┐
26//! │           aimdb-core (trait layer)              │
27//! │  BufferBackend<T> + BufferReader<T> + BufferCfg │
28//! └────────────────┬────────────────────────────────┘
29//!                  │
30//!      ┌───────────┴───────────┐
31//!      │                       │
32//!      ▼                       ▼
33//! ┌─────────────┐     ┌──────────────────┐
34//! │ tokio impl  │     │ embassy impl     │
35//! │ (std)       │     │ (no_std)         │
36//! └─────────────┘     └──────────────────┘
37//! ```
38//!
39//! # Example
40//!
41//! ```rust,ignore
42//! use aimdb_core::buffer::BufferCfg;
43//!
44//! // High-frequency sensor data
45//! reg.buffer(BufferCfg::SpmcRing { capacity: 2048 })
46//!    .source(|em, data| async { ... })
47//!    .tap(|em, data| async { ... });
48//!
49//! // Configuration updates
50//! reg.buffer(BufferCfg::SingleLatest)
51//!    .source(|em, cfg| async { ... })
52//!    .tap(|em, cfg| async { ... });
53//! ```
54
55#[cfg(not(feature = "std"))]
56extern crate alloc;
57
58// Module structure
59mod cfg;
60mod traits;
61
62// Public API exports
63pub use cfg::BufferCfg;
64pub use traits::{Buffer, BufferReader, DynBuffer};
65
66// JSON streaming support (std only)
67#[cfg(feature = "std")]
68pub use traits::JsonBufferReader;
69
70// Buffer metrics (std only, feature-gated)
71#[cfg(feature = "metrics")]
72pub use traits::{BufferMetrics, BufferMetricsSnapshot};
73
74// Re-export buffer-specific errors from core error module
75// These are type aliases for convenience
76pub use crate::DbError as BufferError;
77
78/// Result type for buffer operations
79pub type BufferResult<T> = Result<T, crate::DbError>;
aimdb_core/buffer/mod.rs

aimdb_core/buffer/
mod.rs
