18.2.252. PMIx_server_setup_application

PMIx_server_setup_application — Obtain application-specific setup data (environment, fabric configuration, security credentials) prior to launching a job.

18.2.252.1. SYNOPSIS

#include <pmix_server.h>

pmix_status_t PMIx_server_setup_application(const pmix_nspace_t nspace,
                                            pmix_info_t info[], size_t ninfo,
                                            pmix_setup_application_cbfunc_t cbfunc,
                                            void *cbdata);

18.2.252.1.1. Python Syntax

from pmix import *

foo = PMIxServer()
# ... after a successful foo.init() ...
# dicts is a list of pmix_info_t dictionaries describing the job
# (must include the process and node maps)
dicts = [{'key': PMIX_SETUP_APP_ALL,
          'value': {'value': True, 'val_type': PMIX_BOOL}}]
rc, dataout = foo.setup_application("myapp", dicts)
# dataout is a list of pmix_info_t dictionaries to be distributed
# with the application

18.2.252.2. INPUT PARAMETERS

nspace: The namespace of the job being set up. May be NULL if the request is not scoped to a specific namespace.
info: Array of pmix_info_t(5) structures describing the job and directing what setup data is desired (see DIRECTIVES). The array must include a description of the job via the PMIX_NODE_MAP and PMIX_PROC_MAP attributes.
ninfo: Number of elements in the info array.
cbfunc: Callback function of type pmix_setup_application_cbfunc_t invoked when the setup data is ready (see CALLBACK FUNCTION).
cbdata: Opaque pointer passed, unmodified, to cbfunc.

18.2.252.3. DESCRIPTION

Provide a function by which the host environment (typically a launcher or resource manager) can request application-specific setup data from the supporting PMIx server-library subsystems prior to initiating launch of a job. For example, network libraries may opt to allocate fabric resources and provide security credentials for the application, and programming-model support may harvest relevant environment variables.

PMIx_server_setup_application is a non-blocking operation — it is defined this way because a contributing subsystem may need to perform a potentially time-consuming action (such as querying a remote fabric-manager service) before it can respond. Internally the request is thread-shifted onto the progress thread, where the network (pnet) and programming-model (pmdl) subsystems are given the opportunity to contribute. Whatever data they return is assembled into a pmix_info_t array and handed to cbfunc.

The data returned through the callback must be distributed by the host environment and subsequently delivered, via PMIx_server_setup_local_support(3), to the local PMIx server on each node where the application’s processes will execute, prior to spawning those processes.

The function may be called on a per-application basis if the PMIX_PROC_MAP and PMIX_NODE_MAP describe only the corresponding application rather than the entire job.

As with all non-blocking PMIx APIs, the caller must keep the info array valid until cbfunc is invoked.

18.2.252.4. DIRECTIVES

The following attributes are relevant to this operation. PMIx libraries that support this operation are required to support:

PMIX_SETUP_APP_ENVARS (bool) — harvest and include relevant environment variables.
PMIX_SETUP_APP_NONENVARS (bool) — include all relevant data other than environment variables.
PMIX_SETUP_APP_ALL (bool) — include all relevant data.
PMIX_ALLOC_FABRIC (pmix_data_array_t*) — request fabric allocations, described by the accompanying fabric attributes below.
PMIX_ALLOC_FABRIC_ID (char*) — a string identifier for the requested fabric allocation.
PMIX_ALLOC_FABRIC_SEC_KEY (bool) — a fabric security key is requested.
PMIX_ALLOC_FABRIC_TYPE (char*) — type of desired fabric transport.
PMIX_ALLOC_FABRIC_PLANE (char*) — identifier of the fabric plane to be used for the allocation.
PMIX_ALLOC_FABRIC_ENDPTS (size_t) — number of endpoints to allocate per process.
PMIX_ALLOC_FABRIC_ENDPTS_NODE (size_t) — number of endpoints to allocate per node.
PMIX_PROC_MAP (char*) — regular expression describing the process placement (ranks to nodes) for the job or application.
PMIX_NODE_MAP (char*) — regular expression describing the nodes involved in the job or application.

PMIx libraries may additionally support:

PMIX_ALLOC_BANDWIDTH (float) — fabric bandwidth (in Mbits/sec) being requested.
PMIX_ALLOC_FABRIC_QOS (char*) — fabric quality-of-service level being requested.
PMIX_SESSION_INFO (bool) — in this context, indicates that the PMIX_NODE_MAP describes the entire session rather than just this namespace, allowing subsequent calls to omit node-level information.

The following optional attributes identify the programming model being executed, which the library may use to harvest or forward model-specific environment variables:

PMIX_PROGRAMMING_MODEL (char*) — the programming model (e.g., “MPI”).
PMIX_MODEL_LIBRARY_NAME (char*) — the model library name.
PMIX_MODEL_LIBRARY_VERSION (char*) — the model library version.

18.2.252.5. CALLBACK FUNCTION

The cbfunc has the signature pmix_setup_application_cbfunc_t:

typedef void (*pmix_setup_application_cbfunc_t)(pmix_status_t status,
                                                pmix_info_t info[], size_t ninfo,
                                                void *provided_cbdata,
                                                pmix_op_cbfunc_t cbfunc, void *cbdata);

When the setup data is ready, PMIx invokes cbfunc with the completion status, the info array of setup data to be distributed with the application, and provided_cbdata — the cbdata originally passed to PMIx_server_setup_application.

The returned info array is owned by the PMIx server library and remains valid only until the recipient calls the cbfunc (of type pmix_op_cbfunc_t) that is passed along with it; the library frees the array at that point. Accordingly, the host must copy any data it needs to retain and then invoke that completion function so the library can release its memory. If no data is returned, the info array is NULL, its count is zero, and the trailing cbfunc may be NULL.

18.2.252.6. RETURN VALUE

A return of PMIX_SUCCESS indicates only that the request was accepted for processing; the final status and the setup data are delivered to cbfunc. An immediate error return means the request was not accepted and cbfunc will not be invoked. Possible immediate errors include:

PMIX_ERR_INIT — the PMIx server library has not been initialized.
PMIX_ERR_NOT_AVAILABLE — the operation cannot be serviced because the library’s progress engine has been stopped.
PMIX_ERR_NOMEM — the library was unable to allocate memory for the request.

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

18.2.252.7. NOTES

This is a server-role API, available only after PMIx_server_init(3). Support for harvesting environment variables and providing local configuration information is optional per the Standard; a conforming library may return no data.