18.2.251. PMIx_server_setup_fork

PMIx_server_setup_fork — Set up the environment of a child process that is about to be forked by the host environment.

18.2.251.1. SYNOPSIS

#include <pmix_server.h>

pmix_status_t PMIx_server_setup_fork(const pmix_proc_t *proc, char ***env);

18.2.251.1.1. Python Syntax

from pmix import *

foo = PMIxServer()
# ... after a successful foo.init() ...
proc = {'nspace': "myapp", 'rank': 0}
# envin is a dict that will be updated in place with the
# PMIx environment variables the child requires
envin = {}
rc = foo.setup_fork(proc, envin)

18.2.251.2. INPUT PARAMETERS

proc: Pointer to a pmix_proc_t(5) identifying the namespace and rank of the client process that is about to be launched.

18.2.251.3. INPUT/OUTPUT PARAMETERS

env: Address of the environment array (a NULL-terminated argv-style array of "name=value" strings) for the child process. The array is updated in place: the required PMIx environment variables are added (existing values of the same name are overwritten). The updated array is what the host must pass to the child at fork/exec.

18.2.251.4. DESCRIPTION

Set up the environment of a child process that the host environment is about to fork so that the child’s PMIx client library can correctly connect back to, and interact with, this PMIx server. The host environment is required to call this function for each local client prior to starting that client process.

A PMIx client needs a modest amount of setup information in its environment in order to find and rendezvous with its local server. PMIx_server_setup_fork populates env with the necessary variables, including (among others) the client’s namespace and rank, the server’s rendezvous connection URI, the active security mode, the buffer type and generalized-datastore module in use, the server’s hostname, and the library version. It additionally appends any contributions from the transport, network (pnet), datastore (gds), and programming-model (pmdl) subsystems — for example, temporary-directory settings or the variables a fabric library requires for “instant on” addressing — along with any global environment variables the host registered for distribution to all clients.

This is a blocking operation performed entirely within the local library; it does not involve the host environment or a callback. The variables added here are the counterpart to those the client library consumes during PMIx_Init(3).

Calling PMIx_server_setup_fork for the first local client of a namespace is also the signal that causes any operations cached by a prior call to PMIx_server_setup_local_support(3) to be executed.

18.2.251.5. RETURN VALUE

Returns PMIX_SUCCESS on success, with env updated in place. Otherwise a negative PMIx error constant is returned, including:

PMIX_ERR_INIT — the PMIx server library has not been initialized (see PMIx_server_init(3)).
PMIX_ERR_NOT_AVAILABLE — the operation cannot be serviced because the library’s progress engine has been stopped.

Any other negative value indicates that one of the contributing subsystems (transport, network, datastore, or programming model) failed to add its environmental contribution. PMIx error constants are defined in pmix_common.h.

18.2.251.6. NOTES

This function is a server-role API and is available only after PMIx_server_init(3). The host environment owns the env array and is responsible for freeing it.