.. _man3-PMIx_Query_info: PMIx_Query_info =============== .. include_body ``PMIx_Query_info``, ``PMIx_Query_info_nb`` |mdash| Query information about the system in general. SYNOPSIS -------- .. code-block:: c #include 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); Python Syntax ^^^^^^^^^^^^^ .. code-block:: python3 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 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``. 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 :ref:`pmix_info_cbfunc_t ` invoked with the status and result array once the query completes. * ``cbdata``: Opaque pointer passed, unmodified, to ``cbfunc``. 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 :ref:`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 |mdash| notably the ABI version queries |mdash| 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 (:ref:`PMIx_Init(3) `) and finalization (:ref:`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. 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`` |mdash| return a comma-delimited list of the active namespaces known to the server. * ``PMIX_QUERY_JOB_STATUS`` |mdash| return the status of a specified, currently executing job. * ``PMIX_QUERY_QUEUE_LIST`` |mdash| return a list of scheduler queues. * ``PMIX_QUERY_PROC_TABLE`` / ``PMIX_QUERY_LOCAL_PROC_TABLE`` |mdash| return the process table (all processes, or only those local to a node) for a namespace. * ``PMIX_QUERY_SPAWN_SUPPORT`` |mdash| return a list of the attributes supported by the ``PMIx_Spawn`` API. * ``PMIX_QUERY_MEMORY_USAGE`` |mdash| return memory usage statistics. * ``PMIX_QUERY_ATTRIBUTE_SUPPORT`` |mdash| 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`` |mdash| return the number, or the names, of the defined process sets. * ``PMIX_GROUP_NAMES`` (pmix_data_array_t*) |mdash| 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 :ref:`PMIx_Get(3) ` to retrieve the same information for a single process. * ``PMIX_QUERY_AVAIL_SERVERS`` |mdash| 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`` |mdash| 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 |mdash| introspection and support: * ``PMIX_QUERY_SUPPORTED_KEYS`` (char*) |mdash| return a comma-delimited list of the keys supported by the query function. * ``PMIX_QUERY_DEBUG_SUPPORT`` (char*) |mdash| return a comma-delimited list of the supported debugger attributes. * ``PMIX_QUERY_AUTHORIZATIONS`` (pmix_data_array_t*) |mdash| return the operations the tool is authorized to perform. Namespaces and processes: * ``PMIX_QUERY_NAMESPACE_INFO`` (pmix_data_array_t*) |mdash| 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*) |mdash| return the process IDs of the procs from a given namespace executing on a specified node, as if answering a :ref:`PMIx_Resolve_peers(3) ` request on the caller's behalf. * ``PMIX_QUERY_RESOLVE_NODE`` (char*) |mdash| return a comma-delimited list of the nodes on which procs from a specified namespace have been placed, as if answering a :ref:`PMIx_Resolve_nodes(3) ` request on the caller's behalf. Scheduler, queues, and allocations: * ``PMIX_QUERY_QUEUE_STATUS`` (pmix_data_array_t*) |mdash| 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*) |mdash| return a string reporting the status of an allocation request. Requires a ``PMIX_ALLOC_REQUEST_ID`` qualifier. * ``PMIX_QUERY_ALLOCATION`` (pmix_data_array_t*) |mdash| 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*) |mdash| return the allocation IDs known to the server. * ``PMIX_QUERY_ALLOC_PROPERTIES`` (pmix_data_array_t*) |mdash| 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*) |mdash| return the resources composing the minimum allocatable unit for the system. * ``PMIX_QUERY_RES_BLOCKS`` (pmix_data_array_t*) |mdash| return the names of the currently defined resource blocks. * ``PMIX_QUERY_RES_BLOCK_DEF`` (pmix_data_array_t*) |mdash| 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) |mdash| 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) |mdash| 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*) |mdash| return an array of ``pmix_proc_t`` naming the members of a specified process set. * ``PMIX_QUERY_NUM_GROUPS`` (size_t) |mdash| 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*) |mdash| 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*) |mdash| 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*) |mdash| 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*) |mdash| return the resource-usage statistics for the specified node(s). Accepts ``PMIX_SESSION_ID``, ``PMIX_NSPACE``, or ``PMIX_JOBID`` qualifiers. * ``PMIX_DAEMON_MEMORY`` (float) |mdash| return the amount of memory, in megabytes, currently in use by the PMIx server daemon. * ``PMIX_CLIENT_AVG_MEMORY`` (float) |mdash| return the average amount of memory, in megabytes, in use by the client processes on the node. * ``PMIX_QUERY_DEVICES`` (pmix_data_array_t*) |mdash| 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*) |mdash| 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*) |mdash| the mount point corresponding to the specified storage ID. * ``PMIX_STORAGE_VERSION`` (char*) |mdash| the version string for the storage system. * ``PMIX_STORAGE_MEDIUM`` (pmix_storage_medium_t) |mdash| the storage medium(s) the system uses (e.g., SSD, HDD, tape). See :ref:`pmix_storage_medium_t(5) `. * ``PMIX_STORAGE_ACCESSIBILITY`` (pmix_storage_accessibility_t) |mdash| the accessibility level of the storage system (e.g., node, session). See :ref:`pmix_storage_accessibility_t(5) `. * ``PMIX_STORAGE_PERSISTENCE`` (pmix_storage_persistence_t) |mdash| the persistence level of the storage system (e.g., scratch, archive). See :ref:`pmix_storage_persistence_t(5) `. * ``PMIX_STORAGE_CAPACITY_LIMIT`` (uint64_t) |mdash| the overall capacity of the storage system, in base-2 megabytes. * ``PMIX_STORAGE_CAPACITY_USED`` (double) |mdash| the overall used capacity of the storage system, in bytes. * ``PMIX_STORAGE_OBJECT_LIMIT`` (uint64_t) |mdash| the overall limit on the number of objects (e.g., inodes) in the storage system. * ``PMIX_STORAGE_OBJECTS_USED`` (uint64_t) |mdash| the number of objects currently in use in the storage system. * ``PMIX_STORAGE_BW_CUR`` (double) |mdash| the recently observed bandwidth of the storage system, in bytes/sec. * ``PMIX_STORAGE_BW_MAX`` (double) |mdash| the maximum (theoretical or observed) bandwidth of the storage system, in bytes/sec. * ``PMIX_STORAGE_IOPS_CUR`` (double) |mdash| the recently observed I/O operations per second for the storage system. * ``PMIX_STORAGE_IOPS_MAX`` (double) |mdash| the maximum (theoretical or observed) I/O operations per second for the storage system. * ``PMIX_STORAGE_MINIMAL_XFER_SIZE`` (double) |mdash| the storage system's atomic unit of transfer (e.g., block size), in bytes. * ``PMIX_STORAGE_SUGGESTED_XFER_SIZE`` (double) |mdash| 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*) |mdash| 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*) |mdash| the qualifiers that were included in the query that produced the accompanying results. Commonly used **qualifiers**: * ``PMIX_QUERY_REFRESH_CACHE`` (bool) |mdash| 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) |mdash| scope the query to session-, job-, application-, node-, or process-level information, respectively. * ``PMIX_PROCID`` (pmix_proc_t) |mdash| 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) |mdash| 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) |mdash| 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) |mdash| 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) |mdash| constrain the query to locally available information only, rather than forwarding it to the host environment. * ``PMIX_QUERY_REPORT_AVG`` (bool) |mdash| report average values. * ``PMIX_QUERY_REPORT_MINMAX`` (bool) |mdash| report minimum and maximum values. * ``PMIX_QUERY_SUPPORTED_QUALIFIERS`` (bool) |mdash| 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*) |mdash| identify the storage system whose information is being requested (used with the storage keys above). * ``PMIX_STORAGE_TYPE`` (char*) |mdash| 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) |mdash| for the storage bandwidth, IOPS, and suggested-transfer-size keys, select which access type (read, write, or read/write) to report. See :ref:`pmix_storage_access_type_t(5) `. Qualifiers that are not applicable to a given key are ignored. 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`` |mdash| all requested data was found and returned. * ``PMIX_ERR_PARTIAL_SUCCESS`` |mdash| 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`` |mdash| none of the requested data was available. * ``PMIX_ERR_NOT_SUPPORTED`` |mdash| the host environment does not support this operation. * ``PMIX_ERR_BAD_PARAM`` |mdash| an invalid argument was supplied |mdash| for example, ``nqueries`` of zero, a ``NULL`` ``queries`` array, or a conflicting combination of process-identifier qualifiers. * ``PMIX_ERR_NOT_AVAILABLE`` |mdash| the operation cannot be serviced because the library's progress engine has been stopped. * ``PMIX_ERR_INIT`` |mdash| 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``. 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 |mdash| something the single-key :ref:`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. .. seealso:: :ref:`PMIx_Init(3) `, :ref:`PMIx_Finalize(3) `, :ref:`PMIx_Get(3) `, :ref:`PMIx_Resolve_peers(3) `, :ref:`PMIx_Resolve_nodes(3) `, :ref:`pmix_info_t(5) `, :ref:`pmix_status_t(5) `, :ref:`pmix_query_t(5) `