nvflare.app_common.executors.client_api.in_process_backend module

in_process backend for ClientAPIExecutor.

Ports InProcessClientAPIExecutor’s DataBus machinery behind the frozen ClientAPIBackendSpec surface, with the behavior-parity bar “nothing user-visible”: the trainer script still runs on a thread inside the CJ process, finds its InProcessClientAPI via the DataBus CLIENT_API_KEY entry, receives tasks over TOPIC_GLOBAL_RESULT, and returns results over TOPIC_LOCAL_RESULT.

Differences from the legacy executor (see docs/design/client_api_execution_modes.md):

  • No ParamsConverters and no exchange-format/transfer-type knobs: the Client API boundary passes params through unconverted (ExchangeFormat.RAW) and V1 sends full params (TransferType.FULL); DIFF support returns with the model_registry transfer-type decision, and format conversion moves to send/receive filters at the client edge.

  • LOG data is converted to analytics events through the executor-owned fire_log_analytics() (single analytics-event ownership point), not a direct send_analytic_dxo call.

  • initialize() self-unwinds on failure and finalize() is idempotent and unsubscribes this backend’s DataBus callbacks: the DataBus is a process singleton, so leaked subscriptions would survive into later jobs run in the same process (e.g. the simulator).

class InProcessBackend[source]

Bases: ClientAPIBackendSpec

Runs the trainer script on a thread in the CJ process, bridged over DataBus.

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; close the session lease (without killing the trainer) for attach.

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.

handle_event(event_type: str, fl_ctx: FLContext) → None[source]

Handles an FL event relayed by the executor.

The executor relays events other than START_RUN/END_RUN (those are mapped to initialize/finalize). Backends use this for mode-specific bookkeeping.

Contract: must not raise; log and continue on internal errors.

Parameters:

  • event_type – the fired event type.

  • fl_ctx – the FLContext of the 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/handle_event/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; attach listener/token for attach).

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.