flux-sproc(1)
SYNOPSIS
flux sproc ps [-n] [--rank=RANK] [--service=SERVICE] [--format=FORMAT] flux sproc kill [-w] [--rank=RANK] [--service=SERVICE] SIGNUM PID|LABEL flux sproc wait [--rank=RANK] [--service=SERVICE] PID|LABEL
DESCRIPTION
flux sproc manages subprocesses running under Flux subprocess servers such as rexec and sdexec. It provides commands to list, signal, and wait for remote subprocesses.
Subprocesses can be identified by either process ID (pid) or by label if one was set with flux-exec(1).
COMMANDS
ps
List active and zombie subprocesses.
- -r, --rank=RANK
Send RPC to specified broker rank. The default is FLUX_NODEID_ANY.
- -s, --service=NAME
Query the specified service. The default is rexec.
- -o, --format=FORMAT
Specify output format using Python's string format syntax. Supported field names include pid, state, label, rank, and cmd. The default format is
{pid:>9} {state:<2} {label:<12} {cmd}.If the format string begins with
sort:k1[,k2,...], thenk1[,k2,...]will be taken to be a comma-separated list of keys on which to sort the displayed output. If a sort key starts with-, then the key will be sorted in reverse order.Sort keys can be any valid field name. Fields that may be empty or unset will sort before non-empty values. When sorting fields that contain mixed types, the sort order is: empty/None < numbers (including booleans) < strings. Booleans are treated as numeric values (False=0, True=1).
For example, to sort by a numeric field with empty values first:
--format='sort:nnodes {id} {nnodes} {status}'
Or to sort in reverse order (largest first, empty values last):
--format='sort:-nnodes {id} {nnodes} {status}'
Multiple sort keys can be specified, with earlier keys taking precedence:
--format='sort:state,-t_submit {id} {state} {t_submit}'
- -n, --no-header
Suppress printing of header line.
The state field shows the subprocess state: R for running or Z for zombie (exited but not yet waited on).
kill
Send a signal to a subprocess.
- -r, --rank=RANK
Send RPC to specified broker rank. The default is FLUX_NODEID_ANY.
- -s, --service=NAME
Send signal via the specified service. The default is rexec.
- -w, --wait
Wait for the process to exit and return its exit status. If the process has already exited before flux sproc kill is called and the process is waitable, then an error will be emitted because the kill request will fail, but the command will still exit with the collected exit status from a successful wait.
- SIGNUM
The signal number to send (e.g., 15 for SIGTERM, 9 for SIGKILL).
- PID|LABEL
Process identifier or label. May be a numeric pid or a string label that was set with the
--labeloption of flux-exec(1).
wait
Wait for a waitable subprocess to complete and return its exit status.
Note
This command only works on subprocesses started with the waitable flag, such as those created with flux-exec --bg --waitable. Attempting to wait on a non-waitable process will fail with an error.
- -r, --rank=RANK
Send RPC to specified broker rank. The default is FLUX_NODEID_ANY.
- -s, --service=NAME
Wait via the specified service. The default is rexec.
- PID|LABEL
Process identifier or label. May be a numeric pid or a string label that was set with the
--labeloption of flux-exec(1).
The command exits with the subprocess exit code, or 128 + signal number if the subprocess was terminated by a signal.
EXAMPLES
List all subprocesses on rank 0:
$ flux sproc ps -r 0
Kill a subprocess by pid:
$ flux sproc kill 15 12345
Kill a subprocess by label:
$ flux sproc kill 9 my-process
Wait for a waitable subprocess:
$ flux sproc wait my-background-job
$ echo $?
0
Custom output format:
$ flux sproc ps -n -o '{pid}'
RESOURCES
Flux: http://flux-framework.org
Flux RFC: https://flux-framework.readthedocs.io/projects/flux-rfc
Issue Tracker: https://github.com/flux-framework/flux-core/issues