适用于最小写入单元受限的 Flash 存储的数据库实现 (Database implementation for Flash storage with minimum write unit restrictions). More...

#include <raw.hpp>

Inheritance diagram for LibXR::DatabaseRaw< MinWriteSize >:

Collaboration diagram for LibXR::DatabaseRaw< MinWriteSize >:

Data Structures
struct	BlockBoolData
	按最小写入单元存放布尔位图块 (Boolean flag block stored in one aligned write unit span). More...

class	BlockBoolUtil
	读写对齐布尔位图块的工具 (Helpers for reading and writing aligned boolean flag blocks). More...

struct	FlashInfo
	Flash 存储的块信息结构 (Structure representing a Flash storage block). More...

struct	KeyInfo
	键信息结构，存储键的元数据 (Structure containing key metadata). More...

Public Member Functions
ErrorCode	Get (Database::KeyBase &key) override
	`DatabaseRaw` 的对外生命周期入口区域 / Public lifecycle entry section of `DatabaseRaw`

ErrorCode	Set (KeyBase &key, RawData data) override
	设置数据库中的键值 (Set the key's value in the database).

ErrorCode	Add (KeyBase &key) override
	添加新键到数据库 (Add a new key to the database).

	DatabaseRaw (Flash &flash, size_t recycle_threshold=128)
	构造函数，初始化 Flash 存储和缓冲区 (Constructor to initialize Flash storage and buffer).

void	Init ()
	初始化数据库存储区，确保主备块正确 (Initialize database storage, ensuring main and backup blocks are valid).

void	Restore ()
	还原存储数据，清空 Flash 区域 (Restore storage data, clearing Flash memory area).

ErrorCode	Recycle ()
	回收 Flash 空间，整理数据 (Recycle Flash storage space and organize data).

Private Types
enum class	BlockType : uint8_t { MAIN = 0 , BACKUP = 1 }
	当前 raw 数据库使用的两个物理块角色 / Two physical block roles used by the current raw database More...

Private Member Functions
void	ReadFlashOrExit (size_t offset, RawData data)
	`DatabaseRaw` 的底层 Flash IO 片段 / Low-level Flash-I/O fragment of `DatabaseRaw`

template<typename Data >
void	ReadFlashOrExit (size_t offset, Data &data)
	读取 Flash 数据到对象里，失败则直接触发强约束 (Read flash data into one object and fail fast on error).

void	WriteFlashOrExit (size_t offset, ConstRawData data)
	写入 Flash 数据，失败则直接触发强约束 (Write flash data and fail fast on error).

template<typename Data >
void	WriteFlashOrExit (size_t offset, const Data &data)
	写入一个对象到 Flash，失败则直接触发强约束 (Write one object to flash and fail fast on error).

void	EraseFlashOrExit (size_t offset, size_t size)
	擦除 Flash 区域，失败则直接触发强约束 (Erase a flash range and fail fast on error).

void	CopyFlashData (size_t dst_offset, size_t src_offset, size_t size)
	在两个块之间按最小写入单元复制数据 (Copy data between blocks in minimum-write-size chunks).

size_t	AlignSize (size_t size)
	计算对齐后的大小 (Calculate the aligned size).

ErrorCode	Write (size_t offset, ConstRawData data)
	以最小写入单元对齐的方式写入数据 (Write data aligned to the minimum write unit).

size_t	AvailableSize ()
	`DatabaseRaw` 的块级操作片段 / Block-operation fragment of `DatabaseRaw`

size_t	GetBlockOffset (BlockType block)
	计算指定块的起始偏移 (Compute the starting offset of one block).

size_t	GetChecksumOffset ()
	计算块尾校验区起始偏移 (Compute the starting offset of the checksum area).

size_t	GetChecksumSize ()
	计算块尾校验区字节数 (Compute the byte size of the checksum area).

void	InitBlock (BlockType block)
	把指定块初始化为空数据库块 (Initialize one block as an empty database block).

bool	IsBlockInited (BlockType block)
	判断块头是否已初始化 (Check whether the block header is initialized).

bool	IsBlockEmpty (BlockType block)
	判断块当前是否为空 (Check whether the block is currently empty).

bool	IsBlockError (BlockType block)
	判断块尾校验是否损坏 (Check whether the block checksum is corrupted).

bool	IsBlockValid (BlockType block)
	判断块整体是否处于可用状态 (Check whether the block as a whole is currently usable).

void	InvalidateBlock (BlockType block)
	使指定块尾校验失效 (Invalidate the checksum of one block).

bool	TryGetUsedBlockSize (BlockType block, size_t &used_size)
	试算一个块里已用空间，并在发现布局损坏时提前失败 (Try to compute used block size and fail early on invalid layout).

size_t	GetUsedBlockSize (BlockType block)
	计算一个块当前已用的总字节数 (Compute the currently used byte span of one block).

void	CopyBlockPrefixAndChecksum (BlockType dst_block, BlockType src_block, size_t used_size)
	复制活跃键前缀和块尾校验 (Copy the live key prefix and trailing checksum).

ErrorCode	AddKeyBody (size_t name_len, size_t size, size_t &key_buf_offset)
	`DatabaseRaw` 的键级操作片段 / Key-operation fragment of `DatabaseRaw`

ErrorCode	AddKey (size_t name_offset, size_t name_len, const void *data, size_t size)
	使用现有名字数据新增一个键 (Add one key using an existing name already stored in flash).

ErrorCode	AddKey (const char name, const void data, size_t size)
	按名称新增一个键 (Add one key by name).

ErrorCode	SetKey (const char name, const void data, size_t size, bool recycle=true)
	按名称更新一个键，并在需要时触发回收 (Update one key by name and recycle storage when needed).

size_t	GetKeyData (size_t offset)
	计算某个键的数据区起始偏移 (Compute the starting offset of one key payload).

size_t	GetKeyName (size_t offset)
	计算某个键名字区起始偏移 (Compute the starting offset of one key name).

size_t	GetKeySize (size_t offset)
	计算一个键总共占用的字节数 (Compute the total byte span of one key).

size_t	GetNextKey (size_t offset)
	计算下一键的起始偏移 (Compute the starting offset of the next key).

size_t	GetLastKey (BlockType block)
	计算当前块里最后一个键的偏移 (Locate the last key in the current block).

bool	KeyDataCompare (size_t offset, const void *data, size_t size)
	比较存储中的键数据和给定数据是否不同 (Compare whether the stored payload differs from the given payload).

bool	KeyNameCompare (size_t offset, const char *name)
	比较存储中的键名和给定名称是否不同 (Compare whether the stored key name differs from the given name).

size_t	SearchKey (const char *name)
	在主块里按名称查找键，并在删除项过多时触发回收 (Search one key by name in the main block and trigger recycle when too many tombstones are observed).

Private Attributes
LIBXR_PACKED_END size_t	recycle_threshold_ = 0
	查找时触发回收的失效键阈值 / Tombstone threshold that triggers recycle during lookup

Flash &	flash_
	当前后端绑定的 Flash 设备引用 / Reference to the Flash device bound to this backend

uint32_t	block_size_
	当前主块和备份块各自占用的物理块大小 / Physical block size occupied by each of the main and backup blocks

uint8_t	write_buffer_ [MinWriteSize]
	复用的最小写入单元临时缓冲区 / Reused scratch buffer sized to one minimum write unit

Static Private Attributes
static constexpr uint32_t	FLASH_HEADER
	当前 raw 后端使用的块头签名 / Block-header signature used by the current raw backend

static constexpr uint32_t	CHECKSUM_BYTE = 0x9abcedf0
	当前 raw 后端使用的块尾校验常量 / Trailing checksum constant used by the current raw backend

Detailed Description

template<size_t MinWriteSize>
class LibXR::DatabaseRaw< MinWriteSize >

适用于最小写入单元受限的 Flash 存储的数据库实现 (Database implementation for Flash storage with minimum write unit restrictions).

This class provides key-value storage management for Flash memory that requires data to be written in fixed-size blocks. 此类提供适用于 Flash 存储的键值存储管理，该存储要求数据以固定大小块写入。

Note: 若底层 Flash 读写擦失败，当前实现视为不可恢复故障并直接触发 REQUIRE。 If the underlying Flash read, write, or erase operation fails, the current implementation treats it as an unrecoverable fault and triggers REQUIRE immediately.

Template Parameters

MinWriteSize Flash 的最小写入单元大小 (Minimum write unit size for Flash storage).

Note: 这个头本身只是类壳；真正的布局、底层 IO、块操作、键操作和生命周期流程分别拆在同目录的几个类内片段头里。 This header is only the class shell; the actual layout definitions, low-level I/O helpers, block operations, key operations, and lifecycle flow are split into several class-body fragments in the same directory.

Definition at line 36 of file raw.hpp.

Member Enumeration Documentation

◆ BlockType

template<size_t MinWriteSize>

enum class LibXR::DatabaseRaw::BlockType : uint8_t

strongprivate

当前 raw 数据库使用的两个物理块角色 / Two physical block roles used by the current raw database

One block is treated as the current main data block, while the other acts as the scratch / backup block during recovery and recycle. 一个块承载当前主数据，另一个块在恢复和回收流程里充当暂存 / 备份块。

Enumerator
MAIN	主块 (Main block).
BACKUP	备份块 (Backup block).

Definition at line 11 of file raw.hpp.

                  : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

Constructor & Destructor Documentation

◆ DatabaseRaw()

template<size_t MinWriteSize>

LibXR::DatabaseRaw< MinWriteSize >::DatabaseRaw	(	Flash &	flash,
		size_t	recycle_threshold = 128 )

inlineexplicit

构造函数，初始化 Flash 存储和缓冲区 (Constructor to initialize Flash storage and buffer).

Parameters

flash	目标 Flash 存储设备 (Target Flash storage device).
recycle_threshold	回收阈值 (Recycle threshold).

Definition at line 71 of file raw.hpp.

Member Function Documentation

◆ Add()

template<size_t MinWriteSize>

ErrorCode LibXR::DatabaseRaw< MinWriteSize >::Add ( KeyBase & key )

inlineoverridevirtual

添加新键到数据库 (Add a new key to the database).

Parameters

key	需要添加的键 (Key to add).

Returns: 操作结果 (Operation result).

Implements LibXR::Database.

Definition at line 59 of file raw.hpp.

◆ AddKey() [1/2]

template<size_t MinWriteSize>

ErrorCode LibXR::DatabaseRaw< MinWriteSize >::AddKey	(	const char *	name,
		const void *	data,
		size_t	size )

inlineprivate

按名称新增一个键 (Add one key by name).

Parameters

name	键名 (Key name).
data	键数据地址 (Address of the key payload).
size	键数据字节数 (Payload size in bytes).

Returns: 操作结果 (Operation result).

Definition at line 133 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ AddKey() [2/2]

template<size_t MinWriteSize>

ErrorCode LibXR::DatabaseRaw< MinWriteSize >::AddKey	(	size_t	name_offset,
		size_t	name_len,
		const void *	data,
		size_t	size )

inlineprivate

使用现有名字数据新增一个键 (Add one key using an existing name already stored in flash).

Parameters

name_offset	已存键名在 Flash 中的偏移 (Flash offset of the already stored name).
name_len	键名长度 (Key name length).
data	键数据地址 (Address of the key payload).
size	键数据字节数 (Payload size in bytes).

Returns: 操作结果 (Operation result).

Note: 这个重载给“逻辑更新旧键、但复用旧名字字节”那条路径使用。 This overload is used by the logical-update path that reuses the existing key-name bytes already stored in Flash.

Definition at line 112 of file raw.hpp.

       :
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ AddKeyBody()

template<size_t MinWriteSize>

ErrorCode LibXR::DatabaseRaw< MinWriteSize >::AddKeyBody	(	size_t	name_len,
		size_t	size,
		size_t &	key_buf_offset )

inlineprivate

DatabaseRaw 的键级操作片段 / Key-operation fragment of DatabaseRaw

Note: 这一组函数只负责单个键条目的语义：地址计算、名称比较、数据比较、逻辑追加、以及按名称查找。 This group owns only per-entry semantics: address calculations, name comparisons, data comparisons, logical appends, and name-based lookup.

为新增键预留空间并写入元数据头 (Reserve space for one new key and write its metadata header).

Parameters

name_len	键名长度 (Key name length).
size	数据字节数 (Payload size in bytes).
key_buf_offset	返回新键头偏移 (Receives the new key-header offset).

Returns: 操作结果 (Operation result).

Note: 这个阶段只负责把新键头放到主块尾部，并在必要时把上一键改成“后面还有下一键”；名字区和数据区由调用方随后写入。 This stage only places the new key header at the tail of the main block and, when needed, rewrites the previous key into "has next key"; the name bytes and payload bytes are written by the caller afterwards.

Definition at line 26 of file raw.hpp.

                  : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。

◆ AlignSize()

template<size_t MinWriteSize>

size_t LibXR::DatabaseRaw< MinWriteSize >::AlignSize ( size_t size )

inlineprivate

计算对齐后的大小 (Calculate the aligned size).

Parameters

size	需要对齐的大小 (Size to align).

Returns: 对齐后的大小 (Aligned size).

Definition at line 94 of file raw.hpp.

◆ AvailableSize()

template<size_t MinWriteSize>

size_t LibXR::DatabaseRaw< MinWriteSize >::AvailableSize ( )

inlineprivate

DatabaseRaw 的块级操作片段 / Block-operation fragment of DatabaseRaw

Note: 这一组函数只负责整块语义：块头、尾校验、空块初始化、损坏判断、已用空间计算、以及块间前缀复制。 This group owns only block-level semantics: block headers, trailing checksums, empty-block initialization, corruption checks, used-space accounting, and block-prefix copying.

计算可用的存储空间大小 (Calculate the available storage size).

Returns: 剩余的可用字节数 (Remaining available bytes).

Note: 这里统计的是主块当前已用前缀到块尾校验区之间还剩多少可写空间。 This counts how much writable space remains between the current live prefix of the main block and its trailing checksum area.

Definition at line 20 of file raw.hpp.

24 : octocat-1

◆ CopyBlockPrefixAndChecksum()

template<size_t MinWriteSize>

void LibXR::DatabaseRaw< MinWriteSize >::CopyBlockPrefixAndChecksum	(	BlockType	dst_block,
		BlockType	src_block,
		size_t	used_size )

inlineprivate

复制活跃键前缀和块尾校验 (Copy the live key prefix and trailing checksum).

Parameters

dst_block	目标块类型 (Destination block type).
src_block	源块类型 (Source block type).
used_size	活跃前缀总字节数 (Byte size of the live prefix).

Note: 已擦除尾部不参与复制；只要活跃前缀和块尾校验能重建块语义就够了。 The erased tail is not copied; reproducing the live prefix plus the trailing checksum is sufficient to rebuild the block semantics.

Definition at line 223 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ CopyFlashData()

template<size_t MinWriteSize>

void LibXR::DatabaseRaw< MinWriteSize >::CopyFlashData	(	size_t	dst_offset,
		size_t	src_offset,
		size_t	size )

inlineprivate

在两个块之间按最小写入单元复制数据 (Copy data between blocks in minimum-write-size chunks).

Parameters

dst_offset	目标偏移 (Destination offset).
src_offset	源偏移 (Source offset).
size	待复制字节数 (Byte count to copy).

Definition at line 79 of file raw.hpp.

◆ EraseFlashOrExit()

template<size_t MinWriteSize>

void LibXR::DatabaseRaw< MinWriteSize >::EraseFlashOrExit	(	size_t	offset,
		size_t	size )

inlineprivate

擦除 Flash 区域，失败则直接触发强约束 (Erase a flash range and fail fast on error).

Parameters

offset	擦除偏移 (Erase offset).
size	擦除字节数 (Erase size in bytes).

Definition at line 67 of file raw.hpp.

◆ Get()

template<size_t MinWriteSize>

ErrorCode LibXR::DatabaseRaw< MinWriteSize >::Get ( Database::KeyBase & key )

inlineoverridevirtual

DatabaseRaw 的对外生命周期入口区域 / Public lifecycle entry section of DatabaseRaw

DatabaseRaw 的生命周期与主流程片段 / Lifecycle and main-flow fragment of DatabaseRaw

Note: 这一组函数组成后端真正对外可见的行为：构造时约束检查、启动恢复、运行期读写、显式还原，以及回收流程。 This group forms the backend's externally visible behavior: contract checks during construction, startup recovery, runtime read/write, explicit restore, and recycling flow.

获取数据库中的键值 (Retrieve the key's value from the database).

Parameters

key	需要获取的键 (Key to retrieve).

Returns: 操作结果，如果找到则返回 ErrorCode::OK，否则返回 ErrorCode::NOT_FOUND (Operation result, returns ErrorCode::OK if found, otherwise ErrorCode::NOT_FOUND).

Implements LibXR::Database.

Definition at line 21 of file raw.hpp.

36 : public Database

37{

◆ GetBlockOffset()

template<size_t MinWriteSize>

size_t LibXR::DatabaseRaw< MinWriteSize >::GetBlockOffset ( BlockType block )

inlineprivate

计算指定块的起始偏移 (Compute the starting offset of one block).

Parameters

block 目标块类型 (Target block type).

Returns: 块起始偏移 (Starting offset of the block).

Definition at line 30 of file raw.hpp.

◆ GetChecksumOffset()

template<size_t MinWriteSize>

size_t LibXR::DatabaseRaw< MinWriteSize >::GetChecksumOffset ( )

inlineprivate

计算块尾校验区起始偏移 (Compute the starting offset of the checksum area).

Returns: 块尾校验区起始偏移 (Starting offset of the checksum area).

Definition at line 39 of file raw.hpp.

◆ GetChecksumSize()

template<size_t MinWriteSize>

size_t LibXR::DatabaseRaw< MinWriteSize >::GetChecksumSize ( )

inlineprivate

计算块尾校验区字节数 (Compute the byte size of the checksum area).

Returns: 块尾校验区字节数 (Byte size of the checksum area).

Definition at line 45 of file raw.hpp.

◆ GetKeyData()

template<size_t MinWriteSize>

size_t LibXR::DatabaseRaw< MinWriteSize >::GetKeyData ( size_t offset )

inlineprivate

计算某个键的数据区起始偏移 (Compute the starting offset of one key payload).

Parameters

offset 键头偏移 (Key-header offset).

Returns: 数据区起始偏移 (Starting offset of the payload).

Definition at line 218 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ GetKeyName()

template<size_t MinWriteSize>

size_t LibXR::DatabaseRaw< MinWriteSize >::GetKeyName ( size_t offset )

inlineprivate

计算某个键名字区起始偏移 (Compute the starting offset of one key name).

Parameters

offset 键头偏移 (Key-header offset).

Returns: 名字区起始偏移 (Starting offset of the key name).

Definition at line 231 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ GetKeySize()

template<size_t MinWriteSize>

size_t LibXR::DatabaseRaw< MinWriteSize >::GetKeySize ( size_t offset )

inlineprivate

计算一个键总共占用的字节数 (Compute the total byte span of one key).

Parameters

offset 键头偏移 (Key-header offset).

Returns: 该键占用的总字节数 (Total byte size occupied by the key).

Definition at line 238 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ GetLastKey()

template<size_t MinWriteSize>

size_t LibXR::DatabaseRaw< MinWriteSize >::GetLastKey ( BlockType block )

inlineprivate

计算当前块里最后一个键的偏移 (Locate the last key in the current block).

Parameters

block 目标块类型 (Target block type).

Returns: 最后一个键的偏移；若块为空则返回 0 (Offset of the last key, or 0 when the block is empty).

Definition at line 264 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ GetNextKey()

template<size_t MinWriteSize>

size_t LibXR::DatabaseRaw< MinWriteSize >::GetNextKey ( size_t offset )

inlineprivate

计算下一键的起始偏移 (Compute the starting offset of the next key).

Parameters

offset 当前键头偏移 (Current key-header offset).

Returns: 下一键的起始偏移 (Starting offset of the next key).

Definition at line 251 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ GetUsedBlockSize()

template<size_t MinWriteSize>

size_t LibXR::DatabaseRaw< MinWriteSize >::GetUsedBlockSize ( BlockType block )

inlineprivate

计算一个块当前已用的总字节数 (Compute the currently used byte span of one block).

Parameters

block 目标块类型 (Target block type).

Returns: 当前已用的总字节数 (Currently used byte span of the block).

Definition at line 201 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ Init()

template<size_t MinWriteSize>

void LibXR::DatabaseRaw< MinWriteSize >::Init ( )

inline

初始化数据库存储区，确保主备块正确 (Initialize database storage, ensuring main and backup blocks are valid).

Note: 启动策略是：优先相信合法主块；主块损坏时才尝试从合法且非空的备份块恢复；若主块已好而备份块仍残留，则把备份块失效掉，避免它继续被当作恢复来源。 The startup policy is: trust a valid main block first; recover from a valid non-empty backup block only when the main block is broken; and invalidate any stale backup once the main block is already good so it cannot remain a recovery source.

Definition at line 91 of file raw.hpp.

       :
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ InitBlock()

template<size_t MinWriteSize>

void LibXR::DatabaseRaw< MinWriteSize >::InitBlock ( BlockType block )

inlineprivate

把指定块初始化为空数据库块 (Initialize one block as an empty database block).

Parameters

block 目标块类型 (Target block type).

Note: 初始化后的块是“结构合法但没有任何用户键”的空块：块头有效、首个哨兵键有效、尾校验有效。 After initialization, the block is a structurally valid empty block: valid header, valid sentinel key, and valid trailing checksum.

Definition at line 55 of file raw.hpp.

◆ InvalidateBlock()

template<size_t MinWriteSize>

void LibXR::DatabaseRaw< MinWriteSize >::InvalidateBlock ( BlockType block )

inlineprivate

使指定块尾校验失效 (Invalidate the checksum of one block).

Parameters

block 目标块类型 (Target block type).

Definition at line 133 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ IsBlockEmpty()

template<size_t MinWriteSize>

bool LibXR::DatabaseRaw< MinWriteSize >::IsBlockEmpty ( BlockType block )

inlineprivate

判断块当前是否为空 (Check whether the block is currently empty).

Parameters

block 目标块类型 (Target block type).

Returns: 若块内没有有效键则返回 true (Returns true when the block contains no valid key).

Note: 这里的“空”指只有初始化哨兵，没有任何可发布的用户键。 Here, "empty" means the block contains only the initialized sentinel and no publishable user key.

Definition at line 95 of file raw.hpp.

◆ IsBlockError()

template<size_t MinWriteSize>

bool LibXR::DatabaseRaw< MinWriteSize >::IsBlockError ( BlockType block )

inlineprivate

判断块尾校验是否损坏 (Check whether the block checksum is corrupted).

Parameters

block 目标块类型 (Target block type).

Returns: 若块尾校验不符则返回 true (Returns true when the trailing checksum is invalid).

Definition at line 109 of file raw.hpp.

       :
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.

◆ IsBlockInited()

template<size_t MinWriteSize>

bool LibXR::DatabaseRaw< MinWriteSize >::IsBlockInited ( BlockType block )

inlineprivate

判断块头是否已初始化 (Check whether the block header is initialized).

Parameters

block 目标块类型 (Target block type).

Returns: 若块头有效则返回 true (Returns true when the block header is valid).

Definition at line 78 of file raw.hpp.

◆ IsBlockValid()

template<size_t MinWriteSize>

bool LibXR::DatabaseRaw< MinWriteSize >::IsBlockValid ( BlockType block )

inlineprivate

判断块整体是否处于可用状态 (Check whether the block as a whole is currently usable).

Parameters

block 目标块类型 (Target block type).

Returns: 若块头和校验都有效则返回 true (Returns true when both header and checksum are valid).

Definition at line 124 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ KeyDataCompare()

template<size_t MinWriteSize>

bool LibXR::DatabaseRaw< MinWriteSize >::KeyDataCompare	(	size_t	offset,
		const void *	data,
		size_t	size )

inlineprivate

比较存储中的键数据和给定数据是否不同 (Compare whether the stored payload differs from the given payload).

Parameters

offset	键头偏移 (Key-header offset).
data	待比较数据地址 (Address of the candidate payload).
size	待比较数据字节数 (Payload size in bytes).

Returns: 若内容不同则返回 true (Returns true when the payloads differ).

Definition at line 291 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ KeyNameCompare()

template<size_t MinWriteSize>

bool LibXR::DatabaseRaw< MinWriteSize >::KeyNameCompare	(	size_t	offset,
		const char *	name )

inlineprivate

比较存储中的键名和给定名称是否不同 (Compare whether the stored key name differs from the given name).

Parameters

offset	键头偏移 (Key-header offset).
name	待比较键名 (Key name to compare against).

Returns: 若名称不同则返回 true (Returns true when the names differ).

Definition at line 316 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ ReadFlashOrExit() [1/2]

template<size_t MinWriteSize>

template<typename Data >

void LibXR::DatabaseRaw< MinWriteSize >::ReadFlashOrExit	(	size_t	offset,
		Data &	data )

inlineprivate

读取 Flash 数据到对象里，失败则直接触发强约束 (Read flash data into one object and fail fast on error).

Template Parameters

Data	接收对象类型 (Destination object type).

Parameters

offset	读取偏移 (Read offset).
data	接收数据的对象 (Destination object receiving the data).

Definition at line 32 of file raw.hpp.

◆ ReadFlashOrExit() [2/2]

template<size_t MinWriteSize>

void LibXR::DatabaseRaw< MinWriteSize >::ReadFlashOrExit	(	size_t	offset,
		RawData	data )

inlineprivate

DatabaseRaw 的底层 Flash IO 片段 / Low-level Flash-I/O fragment of DatabaseRaw

Note: 这一组函数只处理“怎么按最小写入单元安全读写 Flash”，不负责数据库条目或块级语义。 This group handles only "how to read and write Flash safely under the minimum write-unit rule"; it does not own database-entry or block-level semantics.

读取 Flash 数据，失败则直接触发强约束 (Read flash data and fail fast on error).

Parameters

offset	读取偏移 (Read offset).
data	接收数据的缓冲区 (Destination buffer receiving the data).

Definition at line 19 of file raw.hpp.

◆ Recycle()

template<size_t MinWriteSize>

ErrorCode LibXR::DatabaseRaw< MinWriteSize >::Recycle ( )

inline

回收 Flash 空间，整理数据 (Recycle Flash storage space and organize data).

Moves valid keys from the main block to the backup block and erases the main block. 将主存储块中的有效键移动到备份块，并擦除主存储块。

Returns: 操作结果 (Operation result).

Note: 当前流程把备份块当作临时整理区：先把主块中的活跃键顺序搬过去，再用备份块的活跃前缀回写主块，最后把备份块重新清为空块。 The current flow treats the backup block as a temporary compaction area: it first copies live keys from the main block into the backup block in order, then rewrites the main block from the backup's live prefix, and finally clears the backup block back to empty.

Definition at line 187 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ Restore()

template<size_t MinWriteSize>

void LibXR::DatabaseRaw< MinWriteSize >::Restore ( )

inline

还原存储数据，清空 Flash 区域 (Restore storage data, clearing Flash memory area).

Note: 这里会把主块和备份块都重新初始化为空块，不保留任何旧键。 This reinitializes both the main block and the backup block into empty blocks and keeps no previous key.

Definition at line 165 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ SearchKey()

template<size_t MinWriteSize>

size_t LibXR::DatabaseRaw< MinWriteSize >::SearchKey ( const char * name )

inlineprivate

在主块里按名称查找键，并在删除项过多时触发回收 (Search one key by name in the main block and trigger recycle when too many tombstones are observed).

Parameters

name	待查找键名 (Key name to search for).

Returns: 找到时返回键头偏移，找不到返回 0 (Returns the key-header offset when found, otherwise 0).

Note: 这里会顺手统计沿途遇到的失效键数量；超过阈值时，查找结束后会先做一次回收，再重新查一遍。 This also counts invalidated keys seen along the scan; when that count exceeds the threshold, it recycles first and then retries the lookup once.

Definition at line 345 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ Set()

template<size_t MinWriteSize>

ErrorCode LibXR::DatabaseRaw< MinWriteSize >::Set	(	KeyBase &	key,
		RawData	data )

inlineoverridevirtual

设置数据库中的键值 (Set the key's value in the database).

Parameters

key	目标键 (Target key).
data	需要存储的新值 (New value to store).

Returns: 操作结果 (Operation result).

Implements LibXR::Database.

Definition at line 49 of file raw.hpp.

◆ SetKey()

template<size_t MinWriteSize>

ErrorCode LibXR::DatabaseRaw< MinWriteSize >::SetKey	(	const char *	name,
		const void *	data,
		size_t	size,
		bool	recycle = true )

inlineprivate

按名称更新一个键，并在需要时触发回收 (Update one key by name and recycle storage when needed).

Parameters

name	键名 (Key name).
data	新数据地址 (Address of the new payload).
size	新数据字节数 (Payload size in bytes).
recycle	是否允许本次调用触发回收 (Whether this call may trigger recycle).

Returns: 操作结果 (Operation result).

Note: 当前实现只支持“同名且同尺寸”的逻辑更新；尺寸不一致时直接返回 ErrorCode::FAILED，不会自动改写布局。 The current implementation supports only logical replacement of the same named key with the same payload size; when the size differs, it returns ErrorCode::FAILED directly and does not rewrite the on-flash layout automatically.

Definition at line 169 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ TryGetUsedBlockSize()

template<size_t MinWriteSize>

bool LibXR::DatabaseRaw< MinWriteSize >::TryGetUsedBlockSize	(	BlockType	block,
		size_t &	used_size )

inlineprivate

试算一个块里已用空间，并在发现布局损坏时提前失败 (Try to compute used block size and fail early on invalid layout).

Parameters

block	目标块类型 (Target block type).
used_size	输出已用字节数 (Receives the used byte size).

Returns: 若成功计算则返回 true (Returns true when the used size is computed successfully).

Note: 这个版本给恢复路径用；它不会假设块内键布局一定合法，而是逐步验证每个键头的位图编码和边界。 This variant is used by recovery paths; it does not assume the key layout is valid and instead verifies each key header's bitmap encoding and bounds incrementally.

Definition at line 154 of file raw.hpp.

{
 
template <size_t MinWriteSize>
class DatabaseRaw : public Database
{
  static constexpr uint32_t FLASH_HEADER =
      0x12345678 + LIBXR_DATABASE_VERSION;
 
  static constexpr uint32_t CHECKSUM_BYTE = 0x9abcedf0;
 
  // 存储布局定义：块角色、位图编码、键头与块头。
  // Storage layout definitions: block roles, bitmap encodings, key headers,
  // and block headers.
#include "layout.hpp"
 
  size_t recycle_threshold_ = 0;
 
  Flash& flash_;
 
  uint32_t block_size_;
 
  uint8_t write_buffer_[MinWriteSize];
 
  // 底层 Flash 读写辅助：按最小写入单元对齐、补齐、复制。
  // Low-level Flash I/O helpers: minimum-write-unit alignment, tail padding,
  // and raw copying.
#include "flash_io.hpp"
 
  // 块级语义：初始化、校验、失效、已用空间计算和块间复制。
  // Block-level semantics: initialization, validation, invalidation,
  // used-space accounting, and block-to-block copying.
#include "block_ops.hpp"
 
  // 键级语义：查找、追加、逻辑更新、条目地址计算。
  // Key-level semantics: lookup, append, logical replacement, and entry
  // address calculations.
#include "key_ops.hpp"
 
 public:
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ Write()

template<size_t MinWriteSize>

ErrorCode LibXR::DatabaseRaw< MinWriteSize >::Write	(	size_t	offset,
		ConstRawData	data )

inlineprivate

以最小写入单元对齐的方式写入数据 (Write data aligned to the minimum write unit).

Parameters

offset	写入偏移量 (Write offset).
data	要写入的数据 (Data to write).

Returns: 操作结果 (Operation result).

Note: 当末尾不足一个最小写入单元时，当前实现会用 0xFF 补齐尾块后再写入。 When the tail is shorter than one minimum write unit, the current implementation pads that final unit with 0xFF before writing it.

Definition at line 109 of file raw.hpp.

       :
  // 对外生命周期与主流程：构造、初始化、读写、恢复、回收。
  // Public lifecycle and main flow: construction, initialization, read/write,
  // restore, and recycle.
#include "lifecycle.hpp"
};
 
}  // namespace LibXR

◆ WriteFlashOrExit() [1/2]

template<size_t MinWriteSize>

template<typename Data >

void LibXR::DatabaseRaw< MinWriteSize >::WriteFlashOrExit	(	size_t	offset,
		const Data &	data )

inlineprivate

写入一个对象到 Flash，失败则直接触发强约束 (Write one object to flash and fail fast on error).

Template Parameters

Data	待写入对象类型 (Object type to write).

Parameters

offset	写入偏移 (Write offset).
data	待写入对象 (Object to write).

Definition at line 56 of file raw.hpp.

◆ WriteFlashOrExit() [2/2]

template<size_t MinWriteSize>

void LibXR::DatabaseRaw< MinWriteSize >::WriteFlashOrExit	(	size_t	offset,
		ConstRawData	data )

inlineprivate

写入 Flash 数据，失败则直接触发强约束 (Write flash data and fail fast on error).

Parameters

offset	写入偏移 (Write offset).
data	待写入数据 (Data to write).

Definition at line 43 of file raw.hpp.

Field Documentation

◆ block_size_

template<size_t MinWriteSize>

uint32_t LibXR::DatabaseRaw< MinWriteSize >::block_size_

private

当前主块和备份块各自占用的物理块大小 / Physical block size occupied by each of the main and backup blocks

Definition at line 81 of file raw.hpp.

◆ CHECKSUM_BYTE

template<size_t MinWriteSize>

uint32_t LibXR::DatabaseRaw< MinWriteSize >::CHECKSUM_BYTE = 0x9abcedf0

staticconstexprprivate

当前 raw 后端使用的块尾校验常量 / Trailing checksum constant used by the current raw backend

Note: 这里不是通用 CRC 计算结果，而是“块已完整写完”的固定尾标记。 This is not a generic computed CRC result; it is the fixed trailing marker meaning "this block has been fully written".

Definition at line 58 of file raw.hpp.

◆ flash_

template<size_t MinWriteSize>

Flash& LibXR::DatabaseRaw< MinWriteSize >::flash_

private

当前后端绑定的 Flash 设备引用 / Reference to the Flash device bound to this backend

Definition at line 75 of file raw.hpp.

◆ FLASH_HEADER

template<size_t MinWriteSize>

uint32_t LibXR::DatabaseRaw< MinWriteSize >::FLASH_HEADER

staticconstexprprivate

Initial value:

=

0x12345678 + LIBXR_DATABASE_VERSION

当前 raw 后端使用的块头签名 / Block-header signature used by the current raw backend

Note: 主块和备份块都用这份签名判断“这个块至少像是同一版 raw 数据库写出来的”。 Both the main block and the backup block use this signature to decide whether the block at least looks like it was written by the same raw database format version.

Definition at line 47 of file raw.hpp.

◆ recycle_threshold_

template<size_t MinWriteSize>

LIBXR_PACKED_END size_t LibXR::DatabaseRaw< MinWriteSize >::recycle_threshold_ = 0

private

查找时触发回收的失效键阈值 / Tombstone threshold that triggers recycle during lookup

Definition at line 69 of file raw.hpp.

◆ write_buffer_

template<size_t MinWriteSize>

uint8_t LibXR::DatabaseRaw< MinWriteSize >::write_buffer_[MinWriteSize]

private

复用的最小写入单元临时缓冲区 / Reused scratch buffer sized to one minimum write unit

Note: 这个缓冲区给尾块补齐和块间复制共用；它不是某个键或某个块长期持有的数据。 This buffer is shared by tail padding and block-to-block copying; it does not store long-lived data owned by one specific key or block.

Definition at line 91 of file raw.hpp.

The documentation for this class was generated from the following file:

src/middleware/database/raw/raw.hpp

Data Structures

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Enumeration Documentation

◆ BlockType

Constructor & Destructor Documentation

◆ DatabaseRaw()

Member Function Documentation

◆ Add()

◆ AddKey() [1/2]

◆ AddKey() [2/2]

◆ AddKeyBody()

◆ AlignSize()

◆ AvailableSize()

◆ CopyBlockPrefixAndChecksum()

◆ CopyFlashData()

◆ EraseFlashOrExit()

◆ Get()

◆ GetBlockOffset()

◆ GetChecksumOffset()

◆ GetChecksumSize()

◆ GetKeyData()

◆ GetKeyName()

◆ GetKeySize()

◆ GetLastKey()

◆ GetNextKey()

◆ GetUsedBlockSize()

◆ Init()

◆ InitBlock()

◆ InvalidateBlock()

◆ IsBlockEmpty()

◆ IsBlockError()

◆ IsBlockInited()

◆ IsBlockValid()

◆ KeyDataCompare()

◆ KeyNameCompare()

◆ ReadFlashOrExit() [1/2]

◆ ReadFlashOrExit() [2/2]

◆ Recycle()

◆ Restore()

◆ SearchKey()

◆ Set()

◆ SetKey()

◆ TryGetUsedBlockSize()

◆ Write()

◆ WriteFlashOrExit() [1/2]

◆ WriteFlashOrExit() [2/2]

Field Documentation

◆ block_size_

◆ CHECKSUM_BYTE

◆ flash_

◆ FLASH_HEADER

◆ recycle_threshold_

◆ write_buffer_