18.2.259. PMIx_server_deliver_inventory

PMIx_server_deliver_inventory — Deliver collected inventory to the PMIx server library for storage.

18.2.259.1. SYNOPSIS

#include <pmix_server.h>

pmix_status_t PMIx_server_deliver_inventory(pmix_info_t info[], size_t ninfo,
                                            pmix_info_t directives[], size_t ndirs,
                                            pmix_op_cbfunc_t cbfunc, void *cbdata);

18.2.259.1.1. Python Syntax

from pmix import *

foo = PMIxServer()
# ... after a successful foo.init() ...
# info carries the inventory to store; directives scope the request
pyinfo = [{'key': PMIX_HOSTNAME,
           'value': {'value': "node01", 'val_type': PMIX_STRING}}]
pydirs = []
rc = foo.deliver_inventory(pyinfo, pydirs)

18.2.259.2. INPUT PARAMETERS

info: Array of pmix_info_t(5) structures containing the inventory to be stored — typically the data previously returned by PMIx_server_collect_inventory(3).
ninfo: Number of elements in the info array.
directives: Array of pmix_info_t(5) structures conveying directives that scope or refine the storage request (see DIRECTIVES). A NULL value (with ndirs of zero) is supported when no directives are desired.
ndirs: Number of elements in the directives array.
cbfunc: Callback function of type pmix_op_cbfunc_t invoked once the library no longer requires access to the provided data. A NULL value makes the call blocking (see DESCRIPTION).
cbdata: Opaque pointer that is passed, unmodified, to cbfunc.

18.2.259.3. DESCRIPTION

Deliver inventory information — obtained from a node via a prior call to PMIx_server_collect_inventory(3) — to the PMIx server library for storage by the corresponding plugins. The library forwards the data to its pnet and pgpu frameworks for archiving.

This function is typically executed on a gateway server associated with the system scheduler, so that the stored inventory can be used by the scheduling algorithm and by the library when responding to PMIx_server_setup_application(3). It may also be used on compute nodes to store a broader picture of the system for access by applications (for example, via the PMIx_Get(3) API, depending on the implementation).

PMIx_server_deliver_inventory supports both blocking and non-blocking operation. When cbfunc is non-NULL the call is non-blocking: it thread-shifts the request into the library’s progress thread, returns immediately, and invokes cbfunc once the library no longer needs the provided data. When cbfunc is NULL the call is blocking: it does not return until the operation has completed. In either case the caller must keep the info and directives arrays valid until the library has finished with them — until cbfunc fires in the non-blocking case, or until the function returns in the blocking case.

18.2.259.4. DIRECTIVES

The directives array scopes and refines the storage request. The specific directives honored are determined by the active pnet and pgpu plugins and are therefore implementation-defined; an unrecognized directive is ignored. Directives that are commonly meaningful include:

PMIX_HOSTNAME (char*) — associate the delivered inventory with a specific host.
PMIX_NODEID (uint32_t) — associate the delivered inventory with a specific node identifier.

18.2.259.5. CALLBACK FUNCTION

For the non-blocking form, the cbfunc has the signature pmix_op_cbfunc_t:

typedef void (*pmix_op_cbfunc_t)(pmix_status_t status, void *cbdata);

The library invokes cbfunc with the final status of the storage operation and the original cbdata once it no longer requires access to the info and directives arrays.

18.2.259.6. RETURN VALUE

For the non-blocking form (cbfunc is non-NULL), a return of PMIX_SUCCESS indicates only that the request was accepted for processing; the final status is delivered through cbfunc. For the blocking form (cbfunc is NULL), a return of PMIX_OPERATION_SUCCEEDED indicates that the request was immediately processed and completed successfully — cbfunc is not called. Possible return values include:

PMIX_SUCCESS — (non-blocking form) the request was accepted for processing.
PMIX_OPERATION_SUCCEEDED — (blocking form) the operation completed successfully.
PMIX_ERR_NOMEM — the library was unable to allocate memory for the request.
PMIX_ERR_NOT_AVAILABLE — the operation cannot be serviced because the library’s progress engine has been stopped.
PMIX_ERR_INIT — the PMIx server library has not been initialized.

Any other negative value indicates an appropriate error condition. PMIx error constants are defined in pmix_common.h.