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 shell is NULL, or either json_str or fmt are NULL, or if shell_rank is 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

Jansson: https://jansson.readthedocs.io/en/2.11/apiref.html