用途
该技能用于获取 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。