Work Subsystem — Technical Summary

Overview

The work subsystem provides a cooperative, single-threaded, asynchronous task-execution framework for stellar-core. It implements a finite state machine (FSM) model where long-running or multi-step tasks are broken into small "cranks" that execute on the main thread without blocking. The framework supports hierarchical task trees, retry logic with exponential backoff, sequential and parallel execution, conditional gating, and orderly abort/shutdown.

All work executes on the main thread via the application's IO service. The subsystem is not thread-safe; the only exception is spawning independent background I/O (file reads, downloads) that post results back to the main thread.

Key Files

• BasicWork.h / BasicWork.cpp — Base FSM class; state machine, retry logic, crank mechanism.
• Work.h / Work.cpp — Extends BasicWork with child-management (hierarchical work trees).
• WorkScheduler.h / WorkScheduler.cpp — Top-level scheduler; posts cranks to the IO service.
• WorkSequence.h / WorkSequence.cpp — Sequential execution of an ordered vector of BasicWork items.
• BatchWork.h / BatchWork.cpp — Parallel batched execution with throttling.
• ConditionalWork.h / ConditionalWork.cpp — Gates a work item on an arbitrary monotonic condition.
• WorkWithCallback.h / WorkWithCallback.cpp — Wraps a simple callback as a one-shot BasicWork.