适用于最小写入单元受限的 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 >:

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.

Detailed Description

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

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

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

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.

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.

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

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.

◆ 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{

◆ Init()

template<size_t MinWriteSize>

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

inline

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

Note: 备份块是一次回收写完的完整拷贝时（见 IsBackupComplete()），回收是在重写主块期间或前后被打断的，主块可能只擦了一部分，因此以备份块为准恢复主块；主块无效时也接受旧版本留下的完整备份块；否则相信有效的主块，主块无效时初始化为空块。仍有键的其他备份块重新准备，不再作为恢复来源。最后检查主块链表，修复掉电留下的状态。 When the backup is the complete copy written by a recycle (see IsBackupComplete()), that recycle was cut while, just before, or just after it rewrote the main block, which may be partly erased, so the main block is restored from the backup; an invalid main block also accepts a complete backup left by older versions; otherwise a valid main block is trusted and an invalid one is initialized empty. Any other backup that still holds keys is prepared again and is no longer a recovery source. The main chain is then checked and repaired after a power loss.

Definition at line 97 of file raw.hpp.

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

◆ 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: 操作结果；整理后连同 CRC 单元仍放不下时不做任何写入，返回 ErrorCode::FULL Operation result; when the compacted keys plus the CRC unit do not fit, nothing is written and ErrorCode::FULL is returned.

Note: 当前流程把备份块当作临时整理区：先把主块链表中的有效键逐个写入备份块，每个键提交后再链接；全部写完后写 CRC 单元和备份块校验，它从此是完整拷贝；再擦除主块、用备份块的有效前缀回写主块，最后重新准备备份块。备份块不处于准备好的状态时先重新准备。 The current flow treats the backup block as a temporary compaction area: it writes the live keys of the main chain into the backup block one by one, linking each key after committing it; after all of them it writes the CRC unit and the backup checksum, which makes the backup the complete copy; it then erases the main block, rewrites it from the backup's live prefix, and finally prepares the backup block again. A backup block that is not in the prepared state is prepared first.

Definition at line 159 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 initializes the main block as an empty block and prepares the backup block again, keeping no previous key.

Definition at line 129 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.

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

src/middleware/database/raw/raw.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ DatabaseRaw()

Member Function Documentation

◆ Add()

◆ Get()

◆ Init()

◆ Recycle()

◆ Restore()

◆ Set()