SuperAPI AI 工具集

subsystem-summary-of-bucket

编程与开发

查看项目

更新于 10-16 06:58

技能介绍

用途

本技能用于在需要时快速、令牌高效地了解 stellar-core 的 Bucket 子系统。Bucket 子系统实现了名为 BucketList 的日志结构合并树(LSM-tree)数据结构,维护所有账本状态的规范化、可哈希验证的表示。

系统中存在两个 BucketList 实例:LiveBucketList(当前账本状态)与 HotArchiveBucketList(最近被逐出的条目)。每个实例组织为 11 个时间层级(第 0 层最年轻/最小,第 10 层最旧/最大),越旧的层级呈指数级增大且变更频率越低。

主要能力

根据资料,该设计目标包括:

  • 提供所有账本条目的单一规范化哈希,而无需在每次账本关闭时重新哈希整个数据库。
  • 支持通过从历史归档进行增量桶下载来实现高效“追赶”(catch-up)。
  • 通过带索引的桶文件(BucketListDB)支持账本条目的点查询与批量查询。

结构要点

桶类型(CRTP 层次)

  • BucketBase<BucketT, IndexT>:不可变、有序、已哈希的 XDR 条目容器的抽象 CRTP 基类,持有文件名、哈希、大小与可选索引,提供核心 merge() 与 mergeInternal() 静态方法。
  • LiveBucket:存储 BucketEntry(INITENTRY、LIVEENTRY、DEADENTRY、METAENTRY),支持 shadows、INIT/DEAD 湮灭与内存中的第 0 层合并。
  • HotArchiveBucket:存储 HotArchiveBucketEntry(HOT_ARCHIVE_ARCHIVED、HOT_ARCHIVE_LIVE、HOT_ARCHIVE_METAENTRY),不支持 shadow。

BucketList 结构

  • BucketListBase<BucketT>:抽象模板基类,包含 BucketLevel<BucketT> 向量,定义了时间分层算法(层级大小为 4 的幂,每层分为 curr 与 snap 两半)。
  • BucketLevel<BucketT>:BucketList 中的单个层级,持有 mCurr、mSnap 与 mNextCurr。
  • LiveBucketList / HotArchiveBucketList:分别扩展上述基类,并加入逐出相关方法与各自的 addBatch()。

BucketManager

BucketManager 是 BucketList 实例、桶文件与合并未来的单例所有者,通过 mBucketMutex 保证桶文件操作的线程安全。职责包括桶文件管理(adoptFileAsBucket、forgetUnreferencedBuckets、cleanupStaleFiles)、合并未来跟踪、批次摄入(addLiveBatch、addHotArchiveBatch)、快照(snapshotLedger)、逐出扫描、状态管理(assumeState、loadCompleteLedgerState)与索引管理(maybeSetIndex)。

合并基础设施

FutureBucket<BucketT> 封装代表进行中或已完成合并的 std::shared_future,具有 5 种状态(FB_CLEAR、FB_HASH_OUTPUT、FB_HASH_INPUTS、FB_LIVE_OUTPUT、FB_LIVE_INPUTS),可通过 cereal 序列化。MergeKey 标识一次合并的输入,BucketMergeMap 提供输入到输出与输出到输入的双向弱映射,用于合并重挂接。

快照与查询层(BucketListDB)

BucketListSnapshotData<BucketT> 是不可变的 BucketList 快照。SearchableBucketListSnapshot<BucketT> 在快照之上提供查询功能,包含 load(LedgerKey) 点查询、loadKeysFromBucket() 批量扫描、loopAllBuckets() 等。BucketSnapshotManager 是主线程 BucketList 变更与只读快照之间的线程安全边界。

索引系统

LiveBucketIndex 封装 InMemoryIndex(小桶)或 DiskIndex<LiveBucket>(大桶),并可选持有用于 ACCOUNT 条目的 RandomEvictionCache;版本为 BUCKET_INDEX_VERSION = 6。HotArchiveBucketIndex 始终使用 DiskIndex,版本为 BUCKET_INDEX_VERSION = 0。DiskIndex 包含 RangeIndex、BinaryFuseFilter16、AssetPoolIDMap、BucketEntryCounters 与 typeRanges。

其他组件

  • 比较与排序:LedgerEntryIdCmp、BucketEntryIdCmp<BucketT>。
  • 追赶支持:BucketApplicator。
  • 逐出:EvictionResultEntry、EvictionResultCandidates、EvictedStateVectors、EvictionStatistics、EvictionMetrics。
  • 工具类型:MergeCounters、BucketEntryCounters、LedgerEntryTypeAndDurability。

关键控制流程

资料列出了三条主要控制流:

  1. 账本关闭(addBatch):BucketManager::addLiveBatch() → LiveBucketList::addBatch() → addBatchInternal(),自上而下遍历层级,第 0 层使用 prepareFirstLevel() 进行同步内存合并,第 1 层及以上通过 FutureBucket 启动后台合并。
  2. 后台合并(FutureBucket::startMerge):构造 MergeKey、检查重挂接、创建 packaged_task 调用 BucketT::merge(),mergeInternal() 处理不同键与相同键的情形。
  3. 点查询(BucketListDB):调用方从 BucketSnapshotManager 获取 SearchableLiveBucketListSnapshot,load(LedgerKey) 遍历所有桶,对每个桶通过 getBucketEntry() 调用索引查询。

适用场景

适用于需要理解、开发或维护 stellar-core Bucket 子系统的场景,例如排查合并与索引进程、了解账本状态快照与查询路径、或研究逐出与追赶机制。

限制

资料为技术摘要,未提供安装命令、收费、价格或平台信息;上述内容仅为子系统设计说明,具体实现细节应以源码为准。