跳转到内容

Runtime API ​

2026-10-10 对账:本页按 HEAD 实况重写(modules/runtime 七头:application_host/ console_event_source/crash_capture/runtime_manifest/service_host/signal_source/ world_host)。旧稿的 Console/Signal/HealthCheck 单例类在仓库中不存在——控制台与信号是 注入式事件源接口(poll 模型),健康检查未实现(P3-3 立项)。

apollo::runtime::ApplicationHost(application_host.hpp) ​

宿主内核:帧驱动托管 IHostedService(start/stop/tick),六阶段状态机 (Boot→ConfigLoaded→Initialized→Ready→Stopping→Stopped),控制台/信号事件源 注入 + 关闭钩子。入口应用一般用同头文件的 ServiceHost 薄包装(二选一)。

cpp
namespace apollo::runtime {
enum class StopReason { Completed = 0, ConsoleRequested, SignalRequested, StartupFailed };

struct ConsoleEvent { std::string command; };
struct SignalEvent  { int value = 0; };

class IHostedService : public apollo::core::IApplicationLifecycle {
public:
    virtual std::string_view service_name() const = 0;
    virtual bool start() = 0;
    virtual void stop() = 0;
    virtual bool is_running() const = 0;
    virtual void tick() {}
};

class IConsoleEventSource { public: virtual bool poll(ConsoleEvent&) = 0; };
class ISignalSource      { public: virtual bool poll(SignalEvent&)  = 0; };

class ApplicationHost {
public:
    using ShutdownHook = std::function<void(StopReason)>;

    void add_service(std::shared_ptr<IHostedService> service);
    void add_shutdown_hook(ShutdownHook hook);
    void set_console_source(std::unique_ptr<IConsoleEventSource> source);
    void set_signal_source(std::unique_ptr<ISignalSource> source);
    void request_stop(StopReason reason);       // async-signal-safe 路径配用

    bool start();                               // 任一服务 start 失败 = false
    int run_once();                             // 单帧:服务 tick + 事件源 poll
    void stop();

    apollo::core::ApplicationPhase phase() const;
    StopReason stop_reason() const;
    bool is_running() const;
};
}

ServiceHost(同头文件)为其薄包装:add_service / add_shutdown_hook / set_console_source / set_signal_source / start / run_once / is_running / stop 逐一转发——测试侧(runtime_comprehensive_tests)即用此形态。

线程安全: 条件安全(request_stop 可自信号处理器调用;装配期单线程)


apollo::runtime::WorldHost(world_host.hpp) ​

世界服务宿主(IHostedService 实现):固定拍率驱动 IWorldService 列表, 默认 10Hz(clock-and-time §3,BW/KBE 同型),拍率可调:

cpp
namespace apollo::runtime {
struct WorldTickContext {
    std::uint64_t tick_index = 0;   // 进程内单调,重启归零,0 = 未启动哨兵
    double delta_seconds = 0.0;
    std::chrono::steady_clock::time_point now{};
};

class IWorldService {
public:
    virtual ~IWorldService() = default;
    virtual std::string_view service_name() const = 0;
    virtual bool initialize() = 0;
    virtual void tick(const WorldTickContext& context) = 0;
    virtual void shutdown() = 0;
};

class WorldHost final : public IHostedService {
public:
    static constexpr std::uint32_t kDefaultTickRate = 10;
    explicit WorldHost(std::uint32_t tick_rate_hz = kDefaultTickRate, NowFn now_fn = ...);

    void set_tick_rate(std::uint32_t tick_rate_hz);
    std::uint32_t tick_rate() const;
    void add_world_service(std::shared_ptr<IWorldService> service);
};
}

固定步长全序推进;追赶有界——单次 tick 至多连跑 kCatchUpMaxSteps 补积压, 超出跳拍 + 告警 + 计 dropped_ticks;时间源可注入(now_fn)便于确定性单测。

线程安全: 不安全(tick 归宿主线程单写者)


apollo::runtime::init_crash_capture(crash_capture.hpp) ​

进程最早段崩溃采集初始化(Crashpad out-of-process handler,本地模式 fail-open):

cpp
namespace apollo::runtime {
struct CrashCaptureStatus {
    bool enabled = false;            // handler 是否成功启动
    bool compiled_in = false;        // 是否带 crashpad(APOLLO_HAS_CRASHPAD)
    std::string database_dir;        // dump 数据库目录
    std::string handler_path;        // 定位到的 handler 可执行文件
    std::size_t pending_reports = 0; // 上次运行遗留 Pending 报告数(sweep)
};

CrashCaptureStatus init_crash_capture(int argc, char* const argv[],
                                      const std::string& proc_name);
}

自扫 --crash-dump-dir / --crash-handler-path(其余参数原样透传);缺省 db = crashdumps/<proc_name>/,handler 三级定位(显式 → 可执行文件同级 → 编译期缓存)。enabled=false 时进程照常继续——采集是增强不是依赖。 全 app main 最早段接线(八 app)。


apollo::runtime::RuntimeManifest(runtime_manifest.hpp) ​

进程装配元数据:struct RuntimeManifest { std::string_view name, layer, description; }, 经 runtime_manifest() 访问器暴露本模块清单(模块自省面)。


runtime 模块不含:交互式控制台与默认信号源(IConsoleEventSource/ ISignalSource 仓库现状只有测试替身——apps 用 csignal 自管 + request_stop 先例见 quick-start)、健康检查设施(health_check.hpp 不存在,P3-3 立项)。

基于 MIT 许可发布