nvflare.app_common.executors.client_api.external_process_backend module

External-process backend for ClientAPIExecutor.

The backend owns the launched trainer process/process group and its authenticated session with the Client Job (CJ) Cell. Task and result Shareables use Cell/F3 directly, including lazy payload transfer. See docs/design/client_api_execution_modes.md and the trainer counterpart in nvflare/client/cell/api.py.

class ExternalProcessBackend[source]

Bases: CellBackendBase

Launches and owns the external trainer process/group, bridged over the CJ cell.

abort(fl_ctx: FLContext) → None[source]

Notify the trainer of task cancellation and latch abortive run teardown.

An accepted lazy result can outlive execute() while another client downloads it. Explicit run abort therefore carries a context marker so it remains distinguishable from normal END_RUN and CCWF task cancellation. Callers predating the marker retain the original run-abort behavior.

execute(task_name: str, shareable: Shareable, fl_ctx: FLContext, abort_signal: Signal) → Shareable[source]

Executes one task on the trainer and returns its result.

The backend delivers the task to the trainer (TASK_READY over Cell, or DataBus for in_process), waits for the result within the executor-configured task/result bounds, and returns the result Shareable.

Contract: this method must always return a Shareable and must not hang past abort: when abort_signal is triggered, the backend notifies/stops the trainer per its mode’s lifecycle ownership and returns make_reply(ReturnCode.TASK_ABORTED). On failure it should return an error reply (e.g. ReturnCode.EXECUTION_EXCEPTION) rather than raise; exceptions that do escape are converted to EXECUTION_EXCEPTION replies by the executor, except UnsafeJobError which the executor lets propagate so ClientRunner can apply its dedicated UNSAFE_JOB handling.

Parameters:

  • task_name – name of the task.

  • shareable – the task data.

  • fl_ctx – the FLContext of the task.

  • abort_signal – checked during execution; triggered means the task is aborted.

Returns:

The result Shareable (an error reply on failure/abort - never None).

finalize(fl_ctx: FLContext) → None[source]

Releases backend resources. Called when the executor handles END_RUN.

The backend tears down per its mode’s lifecycle ownership: stop the in-process trainer thread; send SHUTDOWN and stop the owned process tree (honoring the executor’s shutdown_timeout and stop_grace_period, and pending payload terminal state) for external_process.

Contract: must be idempotent and must not raise. Not called if initialize() raised (see the cleanup-on-failure contract on initialize()).

Parameters:

fl_ctx – the FLContext of the END_RUN event.

initialize(context: ClientAPIBackendContext, fl_ctx: FLContext) → None[source]

Prepares the backend for the run. Called once when the executor handles START_RUN.

context is the frozen snapshot of the executor’s configuration plus a back-reference to the executor (for fire_log_analytics and logging). A backend should read all of its config from context rather than from executor private attributes, and should retain what it needs for execute/finalize.

The backend sets up its control plane here (DataBus wiring for in_process; Cell session machinery, bootstrap config, and - per launch_once policy - trainer launch for external_process).

Contract: raise an exception on any setup failure. The executor converts the exception into system_panic so the job fails cleanly instead of hanging while tasks wait on a backend that never became ready.

Cleanup-on-failure contract: initialize() must be exception-safe and self-unwinding - if it raises, it must first release any partial setup it already made (threads started, processes launched, listeners/tokens registered, files written). The executor does NOT call finalize() on a backend whose initialize() raised, because finalize() cannot assume a consistently half-initialized backend. Own your own rollback.

Parameters:

  • context – the frozen backend configuration and executor back-reference.

  • fl_ctx – the FLContext of the START_RUN event.