Struct WriteBehindWriter 

pub struct WriteBehindWriter { /* private fields */ }

Write-Behind 写入器

包装一个 L2CacheBackend，将写操作同时写入缓存与内存队列， 后台任务或显式 flush() 触发批量刷新到后端存储。

线程安全

内部使用 tokio::sync::Mutex 保护队列，可被多线程并发调用。

示例

use sz_orm_core::l2_cache::{WriteBehindWriter, WriteOp, InMemoryBackend};
use std::sync::Arc;
use std::time::Duration;

let backend = Arc::new(InMemoryBackend::new());
let on_flush = Arc::new(|ops: Vec<WriteOp>| {
    Box::pin(async move {
        // 这里将 ops 应用到数据库（如批量 INSERT/UPDATE）
        for op in &ops {
            println!("flushing: {:?}", op);
        }
        Ok(())
    }) as std::pin::Pin<Box<dyn std::future::Future<Output = Result<(), _>> + Send>>
    as _
});
let writer = WriteBehindWriter::new(backend.clone(), on_flush);

// 立即更新缓存，并异步刷新到数据库
writer.write(b"key1", b"value1", None).await?;

// 显式刷新所有待处理操作
writer.flush().await?;

Implementations

impl WriteBehindWriter

pub fn new(backend: Arc<dyn L2CacheBackend>, on_flush: FlushCallback) -> Self

创建 Write-Behind 写入器

参数

• backend：被包装的 L2 缓存后端（如 InMemoryBackend、RedisBackend）
• on_flush：刷新回调，接收一批操作并应用到后端存储

pub fn with_error_callback(self, on_error: ErrorCallback) -> Self

设置错误回调

当 flush() 失败时调用，传入失败的操作和错误信息。 注意：失败的操作会保留在队列中等待下次重试。

pub async fn write( &self, key: &[u8], value: &[u8], ttl: Option<Duration>, ) -> Result<(), CacheError>

写入缓存（立即更新后端缓存 + 入队待刷新）

参数

• key：缓存键
• value：缓存值（字节切片）
• ttl：TTL，None 表示永不过期

pub async fn delete(&self, key: &[u8]) -> Result<(), CacheError>

删除缓存项（立即从后端缓存删除 + 入队待刷新）

pub async fn flush(&self) -> Result<(), CacheError>

刷新所有待处理操作到后端存储

将队列中的操作一次性传给 on_flush 回调。 若回调返回错误，操作保留在队列中等待下次重试。

pub async fn pending_count(&self) -> usize

当前队列中待刷新的操作数（用于监控）

pub fn spawn_auto_flush(self: Arc<Self>, interval: Duration) -> JoinHandle<()>

启动后台自动刷新任务

每 interval 触发一次 flush()，直到 WriteBehindWriter 被丢弃。 返回 JoinHandle，调用方可用于等待任务结束。

注意

调用方需保证 WriteBehindWriter 的生命周期长于后台任务， 否则在 writer 被丢弃后，后台任务会因 Arc 引用计数归零而停止。