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//! Illustrative (not compiled: `.buffer()` comes from your runtime adapter's
42//! registrar extension trait, which `aimdb-core` cannot depend on):
43//!
44//! ```rust,ignore
45//! use aimdb_core::buffer::BufferCfg;
46//!
47//! // High-frequency sensor data
48//! reg.buffer(BufferCfg::SpmcRing { capacity: 2048 })
49//!    .source(|ctx, producer| async move { /* … */ })
50//!    .tap(|ctx, consumer| async move { /* … */ });
51//!
52//! // Configuration updates
53//! reg.buffer(BufferCfg::SingleLatest)
54//!    .source(|ctx, producer| async move { /* … */ })
55//!    .tap(|ctx, consumer| async move { /* … */ });
56//! ```
57
58// Module structure
59mod cfg;
60#[cfg(feature = "observability")]
61mod counters;
62mod reader;
63mod traits;
64mod writer;
65
66/// Shared buffer conformance suite, invoked from each adapter's own test lane.
67///
68/// `#[doc(hidden)] pub` (not `#[cfg(test)]`) so downstream adapter crates can
69/// call it, mirroring [`crate::executor::test_support`].
70#[doc(hidden)]
71pub mod test_support;
72
73// Public API exports
74pub use cfg::BufferCfg;
75pub use reader::Reader;
76pub use traits::{Buffer, BufferReader, DynBuffer, TryProduceError};
77
78// Crate-private — used by Producer<T> to push without per-call lookup
79pub(crate) use traits::WriteHandle;
80pub(crate) use writer::RecordWriter;
81
82// JSON streaming support
83#[cfg(feature = "remote")]
84pub use reader::JsonReader;
85#[cfg(feature = "remote")]
86pub use traits::JsonBufferReader;
87
88// Buffer metrics (feature-gated; works in no_std with portable-atomic)
89#[cfg(feature = "observability")]
90pub use counters::BufferCounters;
91#[cfg(feature = "observability")]
92pub use traits::{BufferMetrics, BufferMetricsSnapshot};
93
94// Re-export buffer-specific errors from core error module
95// These are type aliases for convenience
96pub use crate::DbError as BufferError;
97
98/// Result type for buffer operations
99pub type BufferResult<T> = Result<T, crate::DbError>;
aimdb_core/buffer/mod.rs

aimdb_core/buffer/
mod.rs
