Flower 框架退出码参考退出码 1GRACEFUL_EXIT_SIGINT与 SIGINT 优雅退出机制源码解析【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower在 FlowerA Friendly Federated AI Framework中进程退出不再只是打印一行日志然后消失每个 Flower 组件SuperLink、SuperNode、Simulation 等都采用统一的退出码Exit Code体系与信号驱动的优雅退出流程。官方参考页 退出码 1 文档 对退出码 1 的定义只有一句话——“The process exited gracefully, triggered by SIGINT.”进程被 SIGINT 触发优雅退出。本篇围绕这条定义展开结合 退出码枚举实现、信号处理器 和统一退出函数 的源码讲清楚退出码 1 是如何被赋值的、SIGINT 信号从触发到进程终止的完整调用链、以及运维侧如何正确区分“优雅退出”与“错误退出”。1. 退出码 1 的含义与所属分类Flower 的退出码参考索引ref-exit-codes-dir.rst将全部退出码划分为若干区段每个区段对应一类组件或一类事件区段含义0-99成功类退出码Success exit codes表示进程正常完成100-199SuperLink 专用退出码flower-superlink的错误200-249 / 250-299ServerApp / ClientApp 专用退出码300-399SuperNode 专用退出码flower-supernode的错误400-499SuperExec 专用退出码flower-superexec的错误600-699通用退出码多个组件共享700-799 / 800-899Simulation / 任务进程退出码退出码 1 位于“成功类退出码”区段。在 exit_code.py 中成功类退出码以常量类的形式集中定义# Success exit codes (0-99) SUCCESS 0 # Successful exit without any errors or signals GRACEFUL_EXIT_SIGINT 1 # Graceful exit triggered by SIGINT GRACEFUL_EXIT_SIGQUIT 2 # Graceful exit triggered by SIGQUIT GRACEFUL_EXIT_SIGTERM 3 # Graceful exit triggered by SIGTERM可以看到成功类退出码共 4 个语义值SUCCESS0表示无任何错误或信号的干净退出而 1、2、3 分别对应由SIGINT、SIGQUIT、SIGTERM三个信号触发的优雅退出。退出码 1 即本文档主题用户按下 CtrlC或向进程发送 SIGINT后Flower 进程走完清理流程再退出时记录的状态。ExitCode类通过重写__new__禁止实例化见 exit_code.py#L80-L82它只作为一个“命名常量命名空间”被各组件引用避免魔法数字散落在代码中。2. SIGINT 如何被映射为退出码 1信号到退出码的映射关系定义在 signal_handler.py#L31-L38SIGNAL_TO_EXIT_CODE: dict[int, int] { signal.SIGINT: ExitCode.GRACEFUL_EXIT_SIGINT, # - 1 signal.SIGTERM: ExitCode.GRACEFUL_EXIT_SIGTERM, # - 3 } # SIGQUIT is not available on Windows if hasattr(signal, SIGQUIT): SIGNAL_TO_EXIT_CODE[signal.SIGQUIT] ExitCode.GRACEFUL_EXIT_SIGQUIT # - 2这里有两个值得注意的实现细节平台差异SIGQUIT在 Windows 上不存在源码通过hasattr(signal, SIGQUIT)做了条件注册。因此在 Windows 平台上实际生效的只有 SIGINT退出码 1和 SIGTERM退出码 3两条映射。信号处理入口各组件启动时调用register_signal_handlers()signal_handler.py#L41-L47完成注册。该函数的参数设计覆盖了优雅退出需要清理的全部资源类型def register_signal_handlers( event_type: EventType, exit_message: str | None None, grpc_servers: list[Server] | None None, bckg_threads: list[Thread] | None None, exit_handlers: list[Callable[[], None]] | None None, ) - None:event_type退出前记录的遥测事件类型如EventType.FLWR_SIMULATION_RUN_LEAVEexit_message退出时打印的上下文消息例如 Simulation 组件传入的Task stopped by user.见 simulation/app.py#L211-L215兼容层start_server传入的则是Flower server terminated gracefully.见 compat/server/app.py#L158-L162grpc_servers/bckg_threads需要在退出前优雅停止的 gRPC 服务器与后台线程exit_handlers额外的自定义清理函数。3. 从 SIGINT 到进程终止的完整调用链当 SIGINT 到达时signal机制调用graceful_exit_handlersignal_handler.py#L85-L107其行为可以归纳为三步防重入用锁保证退出流程只执行一次——连续按 CtrlC 不会触发二次退出逻辑还原默认信号处理器把SIGNAL_TO_EXIT_CODE中每个信号恢复为default_handlers里保存的原始处理器。从源码结构看这一设计的意图是退出流程启动后若用户再次发送同一信号将走 Python 默认行为直接终止进程相当于“强杀兜底”调用统一退出函数flwr_exit(codeSIGNAL_TO_EXIT_CODE[signalnum], messageexit_message, event_typeevent_type)此时 SIGINT 对应的退出码 1 被正式传入。flwr_exitexit.py#L47-L120是所有 Flower 组件的统一出口其执行顺序为is_error not 0 code 100 # 0-99 视为成功/优雅退出 ... log_level ERROR if is_error else INFO sys_exit_code 1 if is_error else 0对退出码 1 而言is_error为 False由此带来三个可验证的行为日志级别优雅退出按 INFO 级别记录错误码≥100才按 ERROR 级别记录日志格式Exit Code: code前缀行仅在错误退出时追加优雅退出时只输出exit_message与短帮助文案退出码 0-3 在EXIT_CODE_HELP中均注册为空字符串见 exit_code.py#L86-L91操作系统层面的退出状态sys_exit_code 0。也就是说虽然 Flower 内部记录的退出码是 1GRACEFUL_EXIT_SIGINT但 shell 中$?看到的进程退出状态是 0。只有错误类退出码才会让进程以状态 1 结束。这是自动化脚本判断 Flower 组件“是被用户停掉”还是“因错误崩溃”时必须结合日志中退出码信息的原因。flwr_exit的其余步骤对优雅退出同样适用遥测上报若指定了event_type发送带exit_code字段的遥测事件并最多等待 constant.py#L148 中定义的TELEMETRY_TIMEOUT_SECONDS4 秒执行第一阶段清理调用trigger_exit_handlers(run_before_force_exitTrue)执行标记为“必须在强杀定时器启动前完成”的处理器启动强杀兜底定时器一个守护线程休眠FORCE_EXIT_TIMEOUT_SECONDSconstant.py#L1465 秒后调用os._exit(sys_exit_code)防止清理逻辑挂死导致进程永远不退执行剩余清理调用trigger_exit_handlers(run_before_force_exitFalse)正式退出sys.exit(sys_exit_code)对退出码 1 即sys.exit(0)。4. 退出处理器Exit Handler机制与清理顺序优雅退出要真正“优雅”关键在于清理函数的注册与执行顺序。该机制实现在 exit_handler.py对外 API 由 exit 包 导出ExitCode、add_exit_handler、flwr_exit、register_signal_handlers。注册add_exit_handler(exit_handler, run_before_force_exitFalse)exit_handler.py#L47-L73把无参可调用对象登记进全局列表并按run_before_force_exit标记分为两阶段执行注册采用threading.Lock保护支持多线程环境下安全注册。执行顺序trigger_exit_handlersexit_handler.py#L76-L93按LIFO后注册先执行顺序调用本阶段处理器且单个处理器抛出的异常会被捕获并忽略——清理失败不会阻塞其他清理逻辑。gRPC 与线程的收尾在register_signal_handlers内部_wait_to_stop被显式注册为退出处理器signal_handler.py#L70-L80它先对每个 gRPC 服务器调用stop(grace1)优雅停机再join()等待后台线程结束。注释中明确其目的是“Ensure that_wait_to_stopis the last handler called on exit”——由于 LIFO 执行且它最先注册网络层资源在所有业务清理之后才被释放。这一机制还向应用开发者开放任何 Flower App 都可以通过add_exit_handler注册自己的清理逻辑例如释放数据集句柄、卸载模型run_before_force_exitTrue表示该清理必须在 5 秒强杀定时器启动前完成。5. 测试与组件侧的实际使用仓库中的单元测试 signal_handler_test.py 验证了这条链路的行为测试中注册退出处理器后通过os.kill(os.getpid(), signal.SIGTERM)向自身进程发送信号确认信号处理器被触发、注册的处理器按预期执行。这与生产路径exit_handler.py#L25-L28 中定义的SIGNAL_TO_EXIT_CODE基础映射保持一致。组件侧的典型接入方式有两类Simulation 组件simulation/app.py#L211-L215传入遥测事件FLWR_SIMULATION_RUN_LEAVE、退出消息Task stopped by user.以及业务清理函数on_exit。因此flwr-simulation运行时按 CtrlC日志会显示该消息内部退出码为 1进程状态为 0。兼容层start_servercompat/server/app.py#L158-L162传入 gRPC 服务器实例使其也纳入_wait_to_stop的优雅停机范围。此外flwr_exit内部还按可执行文件名sys.argv[0]推断默认遥测事件类型如flower-superlink对应RUN_SUPERLINK_LEAVE、flower-supernode对应RUN_SUPERNODE_LEAVE见 exit.py#L124-L142这意味着即使调用方未显式传event_type各组件退出时的遥测事件也能被正确归类。6. 实践要点小结退出码 1 SIGINT 优雅退出当 Flower 组件日志/状态中出现退出码 1GRACEFUL_EXIT_SIGINT说明进程是用户主动中断CtrlC后走完清理流程退出的属于正常行为而非故障同理 2、3 对应 SIGQUIT、SIGTERM。进程退出状态与内部退出码分离0-99 区段的退出码含 1最终都以进程状态 0 结束≥100 的错误码如 201SERVERAPP_EXCEPTION、700SIMULATION_EXCEPTION、800TASK_PROC_EXCEPTION完整清单见 exit_code.py 中的EXIT_CODE_HELP短帮助文案以进程状态 1 结束并会在日志中附上对应的帮助文档页面地址。退出有 5 秒强杀兜底FORCE_EXIT_TIMEOUT_SECONDS 5自定义退出处理器应保持轻量耗时清理逻辑应考虑放入run_before_force_exit之前的阶段或缩短自身耗时。Windows 平台无 SIGQUIT退出码 2 仅在 Unix 系平台可能出现。可扩展性flwr的flwr.supercore.exit包init.py导出add_exit_handler等 API应用层可注册自定义清理钩子与框架内置的 gRPC 优雅停机、线程 join 机制共用同一套 LIFO 执行管线。本文全部结论均可在仓库中逐一对应查证文档定义见 ref-exit-codes/1.rst退出码常量与帮助文案见 exit_code.py信号注册见 signal_handler.py统一退出流程见 exit.py处理器注册与执行见 exit_handler.py超时常量见 constant.py。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考