18.2.17. PMIx_Query_info

PMIx_Query_info, PMIx_Query_info_nb — Query information about the system in general.

18.2.17.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Query_info(pmix_query_t queries[], size_t nqueries,
                              pmix_info_t **results, size_t *nresults);

pmix_status_t PMIx_Query_info_nb(pmix_query_t queries[], size_t nqueries,
                                 pmix_info_cbfunc_t cbfunc, void *cbdata);

18.2.17.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() ...
# each query is a dict with a list of key strings and a list of
# ``pmix_info_t`` qualifier dictionaries
pyq = [{'keys': [PMIX_QUERY_NAMESPACES],
        'qualifiers': []}]
rc, results = foo.query(pyq)
# results is a list of Python ``pmix_info_t`` dictionaries

18.2.17.2. INPUT PARAMETERS

queries: Array of pmix_query_t structures. Each structure carries a NULL-terminated array of string keys identifying the information being requested, plus an optional array of qualifiers (a pmix_info_t array with nqual elements) that refine or scope those keys (see DIRECTIVES).
nqueries: Number of elements in the queries array. Must be non-zero, and queries must be non-NULL.

18.2.17.3. OUTPUT PARAMETERS

results (blocking form): Address where a pointer to a freshly allocated array of pmix_info_t holding the results is returned. Set to NULL when no data is returned. The caller must release the array with PMIX_INFO_FREE.
nresults (blocking form): Address where the number of elements in results is returned; set to zero when no data is returned.

The non-blocking form replaces results/nresults with a callback:

cbfunc: Callback function of type pmix_info_cbfunc_t invoked with the status and result array once the query completes.
cbdata: Opaque pointer passed, unmodified, to cbfunc.

18.2.17.4. DESCRIPTION

Query information about the system in general. This can include a list of active namespaces, the fabric topology, or node-specific information such as the list of peers executing on a given node. Unlike PMIx_Get(3), which retrieves a single key value scoped to a specific session, job, application, process, or node, PMIx_Query_info supports multiple keys per request, complex search criteria expressed through qualifiers, and dynamic system-level information that is not part of the job data provided at start of execution.

PMIx_Query_info is the blocking form: it does not return until the query has completed, at which point results and nresults are set. PMIx_Query_info_nb is the non-blocking form: it returns immediately after accepting the request for processing, and the provided cbfunc is invoked with the final status and result array. The blocking form is implemented in terms of the non-blocking form.

The library first attempts to satisfy each key from its local cache. Keys that cannot be resolved locally are forwarded to the host environment (via the PMIx server) for resolution. A small number of keys — notably the ABI version queries — are always resolved locally. Results returned from the host environment are cached so that subsequent retrievals can succeed with minimal overhead; include the PMIX_QUERY_REFRESH_CACHE qualifier to bypass the cache and obtain fresh values.

PMIx_Query_info is normally called between initialization (PMIx_Init(3)) and finalization (PMIx_Finalize(3)). As an exception, the blocking form may be called before initialization when used exclusively with the PMIX_QUERY_STABLE_ABI_VERSION and/or PMIX_QUERY_PROVISIONAL_ABI_VERSION keys, which are computed entirely within the local library.

As with all non-blocking PMIx APIs, callers of PMIx_Query_info_nb must keep the queries array valid until cbfunc is invoked.

18.2.17.5. DIRECTIVES

Each pmix_query_t combines a list of keys (the information requested) with a list of qualifiers (attributes that scope or refine the request). The most commonly used keys are listed first, followed by the remaining defined keys grouped by purpose, and then the qualifiers. An implementation is not required to support any particular key, and an unsupported key is handled the same way as a key that could not be found. The value type shown for a key is the type of the value it returns; the type shown for a qualifier is the type of data provided with it.

Commonly used keys:

PMIX_QUERY_NAMESPACES — return a comma-delimited list of the active namespaces known to the server.
PMIX_QUERY_JOB_STATUS — return the status of a specified, currently executing job.
PMIX_QUERY_QUEUE_LIST — return a list of scheduler queues.
PMIX_QUERY_PROC_TABLE / PMIX_QUERY_LOCAL_PROC_TABLE — return the process table (all processes, or only those local to a node) for a namespace.
PMIX_QUERY_SPAWN_SUPPORT — return a list of the attributes supported by the PMIx_Spawn API.
PMIX_QUERY_MEMORY_USAGE — return memory usage statistics.
PMIX_QUERY_ATTRIBUTE_SUPPORT — return the attributes supported by a named function. Must appear first in the keys array, followed by the user-level API names (e.g., "PMIx_Get") whose support is being queried.
PMIX_QUERY_NUM_PSETS / PMIX_QUERY_PSET_NAMES — return the number, or the names, of the defined process sets.
PMIX_GROUP_NAMES (pmix_data_array_t*) — return an array of the string names of the process groups in which the given process is a member. The target process is identified with the usual PMIX_PROCID (or PMIX_NSPACE / PMIX_RANK) qualifier. This key may also be passed directly to PMIx_Get(3) to retrieve the same information for a single process.
PMIX_QUERY_AVAIL_SERVERS — scan the local node for PMIx servers the caller could connect to. The result is an array of pmix_info_t, each a PMIX_SERVER_INFO_ARRAY (pmix_data_array_t*) holding the available data for one connectable server (beginning with its namespace). That per-server data includes the server’s PMIX_SERVER_START_TIME (char*), the ctime-format time at which it created its rendezvous file.
PMIX_QUERY_STABLE_ABI_VERSION / PMIX_QUERY_PROVISIONAL_ABI_VERSION — return the stable or provisional Standard ABI version supported by the library. These are resolved locally and may be queried before initialization.

Additional keys, grouped by purpose — introspection and support:

PMIX_QUERY_SUPPORTED_KEYS (char*) — return a comma-delimited list of the keys supported by the query function.
PMIX_QUERY_DEBUG_SUPPORT (char*) — return a comma-delimited list of the supported debugger attributes.
PMIX_QUERY_AUTHORIZATIONS (pmix_data_array_t*) — return the operations the tool is authorized to perform.

Namespaces and processes:

PMIX_QUERY_NAMESPACE_INFO (pmix_data_array_t*) — return an array of information about the active namespaces; each element includes the namespace and the command line of the application executing within it. Accepts an optional PMIX_NSPACE qualifier to select one namespace.
PMIX_QUERY_RESOLVE_PEERS (pmix_data_array_t*) — return the process IDs of the procs from a given namespace executing on a specified node, as if answering a PMIx_Resolve_peers(3) request on the caller’s behalf.
PMIX_QUERY_RESOLVE_NODE (char*) — return a comma-delimited list of the nodes on which procs from a specified namespace have been placed, as if answering a PMIx_Resolve_nodes(3) request on the caller’s behalf.

Scheduler, queues, and allocations:

PMIX_QUERY_QUEUE_STATUS (pmix_data_array_t*) — return the name and status of each scheduler queue. Accepts an optional PMIX_ALLOC_QUEUE qualifier to select one queue.
PMIX_QUERY_ALLOC_STATUS (char*) — return a string reporting the status of an allocation request. Requires a PMIX_ALLOC_REQUEST_ID qualifier.
PMIX_QUERY_ALLOCATION (pmix_data_array_t*) — return an array describing the nodes in an allocation. Accepts a PMIX_ALLOC_ID qualifier to select a specific allocation.
PMIX_QUERY_ALLOC_IDS (pmix_data_array_t*) — return the allocation IDs known to the server.
PMIX_QUERY_ALLOC_PROPERTIES (pmix_data_array_t*) — return the properties of a specific allocation. Requires a PMIX_ALLOC_ID qualifier, and accepts an optional PMIX_ALLOC_PROPERTY qualifier to select a single property.
PMIX_QUERY_MIN_ALLOC_UNIT (pmix_data_array_t*) — return the resources composing the minimum allocatable unit for the system.
PMIX_QUERY_RES_BLOCKS (pmix_data_array_t*) — return the names of the currently defined resource blocks.
PMIX_QUERY_RES_BLOCK_DEF (pmix_data_array_t*) — given a resource block name as its qualifier, return an array of pmix_resource_unit_t describing the resources contained in that block.
PMIX_QUERY_AVAILABLE_SLOTS (uint32_t) — return the number of slots currently available in the session (a point-in-time snapshot). Accepts an optional PMIX_SESSION_ID qualifier.
PMIX_TIME_REMAINING (uint32_t) — return the number of seconds remaining in the allocation for the specified namespace, defaulting to the allocation containing the caller. Accepts an optional PMIX_NSPACE qualifier.

Process sets and groups:

PMIX_QUERY_PSET_MEMBERSHIP (pmix_data_array_t*) — return an array of pmix_proc_t naming the members of a specified process set.
PMIX_QUERY_NUM_GROUPS (size_t) — return the number of process groups defined in the specified range (defaults to the session). Accepts an optional PMIX_RANGE qualifier.
PMIX_QUERY_GROUP_NAMES (pmix_data_array_t*) — return the string names of the process groups defined in the specified range (defaults to the session). Accepts an optional PMIX_RANGE qualifier. Distinct from PMIX_GROUP_NAMES above, which returns the groups a given process belongs to.
PMIX_QUERY_GROUP_MEMBERSHIP (pmix_data_array_t*) — return an array of pmix_proc_t naming the members of a specified process group. Requires a PMIX_GROUP_ID qualifier.

Resource usage, devices, and storage:

PMIX_QUERY_PROC_RESOURCE_USAGE (pmix_proc_t*) — return the resource-usage statistics for the specified process(es). A namespace combined with PMIX_RANK_WILDCARD returns an array with one assembly per process. Accepts PMIX_SESSION_ID, PMIX_NODEID, or PMIX_HOSTNAME qualifiers.
PMIX_QUERY_NODE_RESOURCE_USAGE (char*) — return the resource-usage statistics for the specified node(s). Accepts PMIX_SESSION_ID, PMIX_NSPACE, or PMIX_JOBID qualifiers.
PMIX_DAEMON_MEMORY (float) — return the amount of memory, in megabytes, currently in use by the PMIx server daemon.
PMIX_CLIENT_AVG_MEMORY (float) — return the average amount of memory, in megabytes, in use by the client processes on the node.
PMIX_QUERY_DEVICES (pmix_data_array_t*) — return an array of pmix_device_t for the devices in the current topology that meet the query qualifications, e.g., a PMIX_DEVICE_TYPE qualifier.
PMIX_QUERY_STORAGE_LIST (char*) — return a comma-delimited list of identifiers for all available storage systems.

Storage system information. PMIX_QUERY_STORAGE_LIST returns the available storage-system identifiers; the following keys return the properties of a particular system, selected with a PMIX_STORAGE_ID qualifier:

PMIX_STORAGE_PATH (char*) — the mount point corresponding to the specified storage ID.
PMIX_STORAGE_VERSION (char*) — the version string for the storage system.
PMIX_STORAGE_MEDIUM (pmix_storage_medium_t) — the storage medium(s) the system uses (e.g., SSD, HDD, tape). See pmix_storage_medium_t(5).
PMIX_STORAGE_ACCESSIBILITY (pmix_storage_accessibility_t) — the accessibility level of the storage system (e.g., node, session). See pmix_storage_accessibility_t(5).
PMIX_STORAGE_PERSISTENCE (pmix_storage_persistence_t) — the persistence level of the storage system (e.g., scratch, archive). See pmix_storage_persistence_t(5).
PMIX_STORAGE_CAPACITY_LIMIT (uint64_t) — the overall capacity of the storage system, in base-2 megabytes.
PMIX_STORAGE_CAPACITY_USED (double) — the overall used capacity of the storage system, in bytes.
PMIX_STORAGE_OBJECT_LIMIT (uint64_t) — the overall limit on the number of objects (e.g., inodes) in the storage system.
PMIX_STORAGE_OBJECTS_USED (uint64_t) — the number of objects currently in use in the storage system.
PMIX_STORAGE_BW_CUR (double) — the recently observed bandwidth of the storage system, in bytes/sec.
PMIX_STORAGE_BW_MAX (double) — the maximum (theoretical or observed) bandwidth of the storage system, in bytes/sec.
PMIX_STORAGE_IOPS_CUR (double) — the recently observed I/O operations per second for the storage system.
PMIX_STORAGE_IOPS_MAX (double) — the maximum (theoretical or observed) I/O operations per second for the storage system.
PMIX_STORAGE_MINIMAL_XFER_SIZE (double) — the storage system’s atomic unit of transfer (e.g., block size), in bytes.
PMIX_STORAGE_SUGGESTED_XFER_SIZE (double) — the suggested transfer size for the storage system, in bytes.

The bandwidth, IOPS, and suggested-transfer-size keys may be further qualified by PMIX_STORAGE_ACCESS_TYPE to select read, write, or read/write access.

The following two keys appear only in returned results and cannot be used as input to PMIx_Query_info or PMIx_Get:

PMIX_QUERY_RESULTS (pmix_data_array_t*) — the array of results produced for a given pmix_query_t. When the query carried qualifiers, the first element is a PMIX_QUERY_QUALIFIERS entry; each remaining element is a pmix_info_t pairing a queried key with its returned value.
PMIX_QUERY_QUALIFIERS (pmix_data_array_t*) — the qualifiers that were included in the query that produced the accompanying results.

Commonly used qualifiers:

PMIX_QUERY_REFRESH_CACHE (bool) — bypass the local cache and retrieve a fresh value, refreshing the cache on return. Required on each query for which current (non-cached) data is needed.
PMIX_SESSION_INFO / PMIX_JOB_INFO / PMIX_APP_INFO / PMIX_NODE_INFO / PMIX_PROC_INFO (bool) — scope the query to session-, job-, application-, node-, or process-level information, respectively.
PMIX_PROCID (pmix_proc_t) — identify the specific process whose information is being requested. The identifier applies to every key in that pmix_query_t.
PMIX_NSPACE (char*) / PMIX_RANK (pmix_rank_t) — identify a specific process by namespace and rank. These must be used together. Combining PMIX_PROCID with either PMIX_NSPACE or PMIX_RANK in the same query yields PMIX_ERR_BAD_PARAM.
PMIX_CLIENT_ATTRIBUTES / PMIX_SERVER_ATTRIBUTES / PMIX_HOST_ATTRIBUTES / PMIX_TOOL_ATTRIBUTES (bool) — when used with PMIX_QUERY_ATTRIBUTE_SUPPORT, select the level(s) of attribute support to report. Omitting all levels is equivalent to requesting every level.
PMIX_CLIENT_FUNCTIONS / PMIX_SERVER_FUNCTIONS / PMIX_TOOL_FUNCTIONS / PMIX_HOST_FUNCTIONS (bool) — when used with PMIX_QUERY_ATTRIBUTE_SUPPORT, return a comma-delimited list of the PMIx functions supported at the client, server, tool, or host level, respectively (in place of the per-function attribute listing produced by the corresponding PMIX_*_ATTRIBUTES qualifier).
PMIX_QUERY_LOCAL_ONLY (bool) — constrain the query to locally available information only, rather than forwarding it to the host environment.
PMIX_QUERY_REPORT_AVG (bool) — report average values.
PMIX_QUERY_REPORT_MINMAX (bool) — report minimum and maximum values.
PMIX_QUERY_SUPPORTED_QUALIFIERS (bool) — return a comma-delimited list of the qualifiers supported for the provided key, instead of performing the query on that key.
PMIX_STORAGE_ID (char*) — identify the storage system whose information is being requested (used with the storage keys above).
PMIX_STORAGE_TYPE (char*) — restrict a storage query to systems of the given type (e.g., lustre, gpfs, fabric-attached).
PMIX_STORAGE_ACCESS_TYPE (pmix_storage_access_type_t) — for the storage bandwidth, IOPS, and suggested-transfer-size keys, select which access type (read, write, or read/write) to report. See pmix_storage_access_type_t(5).

Qualifiers that are not applicable to a given key are ignored.

18.2.17.6. RETURN VALUE

For the blocking form, PMIX_SUCCESS indicates that all requested data was found and returned in results. For the non-blocking form, PMIX_SUCCESS indicates only that the request was accepted for processing; the final status and results are delivered to cbfunc. In both cases the possible completion statuses include:

PMIX_SUCCESS — all requested data was found and returned.
PMIX_ERR_PARTIAL_SUCCESS — only some of the requested data was found; the result array contains an element for each key that returned a value.
PMIX_ERR_NOT_FOUND — none of the requested data was available.
PMIX_ERR_NOT_SUPPORTED — the host environment does not support this operation.
PMIX_ERR_BAD_PARAM — an invalid argument was supplied — for example, nqueries of zero, a NULL queries array, or a conflicting combination of process-identifier qualifiers.
PMIX_ERR_NOT_AVAILABLE — the operation cannot be serviced because the library’s progress engine has been stopped.
PMIX_ERR_INIT — the PMIx library has not been initialized (and the query was not one of the locally resolvable ABI-version queries).

When a value other than PMIX_SUCCESS or PMIX_ERR_PARTIAL_SUCCESS is the completion status, the result array is NULL and its count is zero. Any other negative value indicates an appropriate error condition. PMIx error constants are defined in pmix_common.h.

18.2.17.7. NOTES

The returned results array (blocking form) or the array delivered to cbfunc (non-blocking form) is owned by the caller and must be released with PMIX_INFO_FREE when no longer needed.

Because a query can carry multiple keys and qualifiers, it is well suited to retrieving a multi-attribute block of data in a single request — something the single-key PMIx_Get(3) API cannot do. For a single static key value, however, PMIx_Get is typically faster because it avoids the overhead of constructing and processing the pmix_query_t structure.