SuperAPI AI 工具集

subsystem-summary-of-work

编程与开发

查看项目

更新于 10-16 06:39

技能介绍

用途

该技能用于获取 stellar-core 中 work 子系统的令牌高效技术摘要。work 子系统为 stellar-core 提供协作式、单线程、异步的任务执行框架,采用有限状态机(FSM)模型,将长时间运行或多步骤任务拆分为不阻塞主线程的小型“crank”。框架支持分层任务树、带指数退避的重试逻辑、顺序与并行执行、条件门控以及有序中止/关闭。

主要能力

  • 有限状态机:每个工作单元继承自 BasicWork,具有公开状态(WORK_RUNNING、WORK_WAITING、WORK_SUCCESS、WORK_FAILURE、WORK_ABORTED)和内部状态(PENDING、RETRYING、ABORTING)。
  • 分层任务树:Work 类扩展 BasicWork,支持管理子工作项,形成树状结构,实现监督者模式。
  • 重试逻辑:支持指数退避重试,常量包括 RETRY_NEVER、RETRY_ONCE、RETRY_A_FEW、RETRY_A_LOT。
  • 顺序执行:WorkSequence 按严格顺序执行 BasicWork 向量。
  • 并行批处理:BatchWork 按 MAX_CONCURRENT_SUBPROCESSES 节流并行执行工作项。
  • 条件门控:ConditionalWork 基于单调条件函数门控被包装工作的执行。
  • 回调包装:WorkWithCallback 将简单回调包装为一次性 BasicWork。
  • 调度器:WorkScheduler 作为顶层调度器,将 crank 投递到 IO 服务。

使用方式

该技能本身为技术摘要文档,供阅读以了解 work 子系统的架构与实现细节。实际使用中,开发者通过继承 BasicWork 并实现 onRun() 和 onAbort() 来定义工作单元;通过 Work 的 addWork 模板方法添加子工作;通过 WorkScheduler::scheduleWork 调度工作;通过 WorkScheduler::executeWork 同步执行工作。

适用场景

适用于需要理解或修改 stellar-core 中异步任务执行框架的开发者,例如实现新的后台任务、调试任务调度问题、优化任务执行流程等。

限制

  • 所有工作在主线程通过应用的 IO 服务执行,子系统非线程安全。
  • 唯一例外是派生独立后台 I/O(文件读取、下载),并将结果回传主线程。
  • 具体实现细节需参考源代码文件。

核心类与数据结构

BasicWork

基础有限状态机,所有工作单元均派生自此类。

公开状态枚举:WORK_RUNNING、WORK_WAITING、WORK_SUCCESS、WORK_FAILURE、WORK_ABORTED。

内部状态枚举:PENDING、RETRYING、ABORTING。

关键成员:mApp、mName、mState、mRetries/mMaxRetries、mRetryTimer、mWaitingTimer、mNotifyCallback、ALLOWED_TRANSITIONS。

关键方法:crankWork()、startWork()、shutdown()、isDone()、getState()、setState()、wakeUp()、wakeSelfUpCallback()、setupWaitingCallback()、waitForRetry()、reset()。

纯虚函数:onRun()、onAbort()。

虚生命周期回调:onReset()、onSuccess()、onFailureRetry()、onFailureRaise()。

Work

扩展 BasicWork,增加子工作管理能力。

关键成员:mChildren、mNextChild、mDoneChildren/mTotalChildren、mAbortChildrenButNotSelf。

关键方法:addWork<T>()、addWorkWithCallback<T>()、addWork()、onRun()、onAbort()、onReset()、yieldNextRunningChild()、checkChildrenStatus()、shutdown()、clearChildren()。

纯虚函数:doWork()。

虚函数:doReset()。

WorkScheduler

顶层工作调度器,每个应用一个实例。

关键成员:mScheduled、mTriggerTimer、TRIGGER_PERIOD(50ms)。

关键方法:create()、scheduleWork<T>()、executeWork<T>()、scheduleOne()、doWork()、shutdown()。

WorkSequence

按严格顺序执行 BasicWork 向量。

关键成员:mSequenceOfWork、mNextInSequence、mCurrentExecuting、mStopAtFirstFailure。

关键方法:onRun()、onAbort()、onReset()、shutdown()。

BatchWork

并行批处理执行,受 MAX_CONCURRENT_SUBPROCESSES 节流。

关键成员:mBatch。

关键方法:doWork()、addMoreWorkIfNeeded()、doReset()。

纯虚函数:hasNext()、yieldMoreWork()、resetIter()。

ConditionalWork

基于单调条件门控被包装工作。

关键成员:mCondition、mConditionedWork、mSleepDelay(默认100ms)、mWorkStarted。

关键方法:onRun()、onAbort()、onReset()、shutdown()。

WorkWithCallback

一次性回调包装。

关键成员:mCallback。

关键方法:onRun()、onAbort()。

状态机与生命周期

FSM 具有 8 个内部状态和 16 个合法转换。生命周期流程:创建(PENDING)→ 启动(startWork 转 RUNNING)→ 反复 crank(crankWork 调用 onRun)→ 等待(返回 WAITING 时通过 wakeUp 唤醒)→ 终止(SUCCESS/FAILURE/ABORTED)。

关键文件

  • BasicWork.h / BasicWork.cpp
  • Work.h / Work.cpp
  • WorkScheduler.h / WorkScheduler.cpp
  • WorkSequence.h / WorkSequence.cpp
  • BatchWork.h / BatchWork.cpp
  • ConditionalWork.h / ConditionalWork.cpp
  • WorkWithCallback.h / WorkWithCallback.cpp

类层次结构

BasicWork(基类 FSM,抽象) ├── Work(增加子管理,抽象) │ ├── WorkScheduler(顶层调度器) │ └── BatchWork(并行批处理,抽象) ├── WorkSequence(顺序执行向量) ├── ConditionalWork(条件门控委托) └── WorkWithCallback(一次性回调包装)

所有类继承 std::enable_shared_from_this<BasicWork> 和 NonMovableOrCopyable,所有权通过 std::shared_ptr。