18.2.253. PMIx_server_setup_local_support

PMIx_server_setup_local_support — Perform application-specific local setup operations prior to spawning local clients of a namespace.

18.2.253.1. SYNOPSIS

#include <pmix_server.h>

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

18.2.253.1.1. Python Syntax

from pmix import *

foo = PMIxServer()
# ... after a successful foo.init() ...
# ilist is the list of pmix_info_t dictionaries returned by the
# earlier setup_application call and distributed by the host
rc = foo.setup_local_support("myapp", ilist)

18.2.253.2. INPUT PARAMETERS

nspace: The namespace whose local support is being set up. May be NULL if the operation is not scoped to a specific namespace.
info: Array of pmix_info_t(5) structures. This is the data returned to the host by the callback of the corresponding PMIx_server_setup_application(3) call and distributed to this node. May be NULL with ninfo of zero.
ninfo: Number of elements in the info array.
cbfunc: Callback function of type pmix_op_cbfunc_t invoked when the operation completes. A NULL value makes the call blocking (see DESCRIPTION).
cbdata: Opaque pointer passed, unmodified, to cbfunc.

18.2.253.3. DESCRIPTION

Provide a function by which the local PMIx server can perform any application-specific operations required before spawning local clients of a given namespace. For example, a fabric library might need to program the local driver for “instant on” addressing. The info array delivered here is the data that was produced on some node by PMIx_server_setup_application(3) and then distributed by the host environment to every node that will run the application’s processes.

Data provided in the info array is stored in the job-information region for the namespace. Operations implied by that data are cached until the server first calls PMIx_server_setup_fork(3) for the namespace, thereby indicating that a local client of the namespace is actually about to be started. Such operations are executed only once per namespace — for the first local client — not once per client.

Internally the request is thread-shifted onto the progress thread, where the network (pnet) subsystem is given the opportunity to set up the local network support. The completion status of that subsystem operation is delivered as the result.

PMIx_server_setup_local_support supports both calling conventions. When cbfunc is non-NULL the function is non-blocking: it returns immediately, and cbfunc is invoked with the completion status. When cbfunc is NULL the function is blocking: it does not return until the operation completes and the result is carried by the return value (see RETURN VALUE).

The host environment is required to execute this operation prior to starting any local application process of the namespace if setup data was obtained from a call to PMIx_server_setup_application. The host must also have registered the namespace with PMIx_server_register_nspace(3) before calling this API, so that all namespace-related information the library needs is already available.

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

18.2.253.4. CALLBACK FUNCTION

When cbfunc is provided, it has the signature pmix_op_cbfunc_t:

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

It is invoked with the completion status of the local-support operation and the cbdata originally passed to PMIx_server_setup_local_support.

18.2.253.5. RETURN VALUE

For the non-blocking form (cbfunc non-NULL), a return of PMIX_SUCCESS indicates only that the request was accepted for processing; the final status is delivered to cbfunc.

For the blocking form (cbfunc is NULL), a return of PMIX_OPERATION_SUCCEEDED indicates that the operation completed successfully and no callback is (or was) invoked. Other returns 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.253.6. NOTES

This is a server-role API, available only after PMIx_server_init(3). Because the implied operations are executed only for the first local client of a namespace, calling this API has no additional effect once PMIx_server_setup_fork(3) has already fired those operations for that namespace.