flux_shell_get_info(3)
SYNOPSIS
#include <flux/shell.h>
#include <errno.h>
int flux_shell_get_info (flux_shell_t *shell,
char **json_str);
int flux_shell_info_unpack (flux_shell_t *shell,
const char *fmt,
...);
int flux_shell_get_rank_info (flux_shell_t *shell,
int shell_rank,
char **json_str);
int flux_shell_rank_info_unpack (flux_shell_t *shell,
int shell_rank,
const char *fmt,
...);
Link with -lflux-core.
DESCRIPTION
flux_shell_get_info() returns shell information as a json string
with the following layout:
"jobid":I,
"instance_owner":i,
"rank":i,
"size":i,
"ntasks":i,
"service":s,
"options": { "verbose":b, "standalone":b },
"constrained_resources":b,
"jobspec":o,
"R":o
where constrained_resources indicates that the job's access to
resources has been constrained to its allocation, as configured by
exec.sdexec-constrain-resources in flux-config-exec(5). The value
is always present.
Resource ids in R and in the rank info object are not affected by
this setting: they are always the ids assigned by the enclosing instance.
When resources are constrained, however, tools and libraries that enumerate
devices see only the subset available to the job and index them from zero,
so those ids are not valid indices within the library. A plugin that
translates resource ids from R into identifiers for use outside
Flux must account for this. For example, the builtin gpu-affinity
plugin sets its GPU visibility variable to the position of each allocated
GPU within the rank's allocation rather than to its id from R.
flux_shell_get_rank_info() returns shell rank information as a json
string with the following layout:
"id":i,
"name":s,
"broker_rank":i,
"ntasks":i,
"taskids":s,
"resources": { "ncores":i, "cores":s, ... }
where id is the shell rank, name is the hostname of that shell
rank, broker_rank is the broker rank on which the target shell rank
of the query is running, ntasks is the number of tasks running under
that shell rank, taskids is a list of task id assignments for those
tasks (an RFC 22 idset string), and resources is a dictionary of
resource name to resource ids assigned to the shell rank.
flux_shell_info_unpack() and flux_shell_rank_info_unpack()
accomplish the same thing with Jansson-style formatting arguments.
If shell_rank is set to -1, the current shell rank is used.
RETURN VALUE
All functions return 0 on success and -1 on error.
ERRORS
- EINVAL
if
shellis NULL, or eitherjson_strorfmtare NULL, or ifshell_rankis less than -1.
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