nvflare.utils.process_utils module

class ProcessAdapter(process: Popen | None = None, pid: int | None = None)

Bases: object

Adapter to manage a process, whether created via subprocess.Popen or os.posix_spawn.

Parameters:

• process – The subprocess.Popen object (if created via subprocess)

• pid – The process ID (if created via posix_spawn, or fallback for process.pid)

poll() → int | None

Check if the process has terminated.

Returns:

None if process is still running, otherwise the exit code.

terminate() → None

Terminate the process group.

Sends SIGKILL to the entire process group. No need to call process.terminate() separately since SIGKILL already terminates all processes in the group.

wait() → None

Wait for the process to terminate.

log_subprocess_output(process, logger) → None

Drain a subprocess’s merged stdout/stderr stream and route complete lines.

prepare_subprocess_command(command: str | Sequence[str]) → list[str]

Build argv for a shell-free subprocess command and resolve secret references safely.

The command is split before references are resolved, so a secret containing spaces or command-line metacharacters remains one argv element. References inside recognized nested interpreter command strings are rejected because those strings are parsed a second time.

Parameters:

command – Command string or pre-tokenized argv from job configuration.

Returns:

A resolved argv list suitable for subprocess.Popen(..., shell=False).

spawn_process(cmd_args: List[str], env: dict) → ProcessAdapter

Launch a process using posix_spawn if available, falling back to subprocess.Popen.

This method attempts to use os.posix_spawn with setsid=True to avoid fork() related issues (such as gRPC deadlocks). If posix_spawn is unavailable or fails, it falls back to subprocess.Popen with preexec_fn=os.setsid.

Parameters:

• cmd_args – The command arguments as a list of strings.

• env – The environment variables dictionary.

Returns:

An adapter wrapping the launched process.

Return type:

ProcessAdapter