18.2.245. PMIx_server_init

PMIx_server_init — Initialize the PMIx server support library.

18.2.245.1. SYNOPSIS

#include <pmix_server.h>

pmix_status_t PMIx_server_init(pmix_server_module_t *module,
                               pmix_info_t info[], size_t ninfo);

18.2.245.1.1. Python Syntax

from pmix import *

foo = PMIxServer()
# the directives is a list of Python ``pmix_info_t`` dictionaries
pydirs = [{'key': PMIX_SERVER_NSPACE,
           'value': {'value': "SERVER", 'val_type': PMIX_STRING}}]
# map is a dictionary of server-module-function keys to Python
# callback implementations (e.g. {'clientconnected': myconnfn, ...})
rc = foo.init(pydirs, map)

18.2.245.2. INPUT PARAMETERS

module: Pointer to a pmix_server_module_t(5) structure containing the host environment’s callback functions — the “function-shipped” server module through which client requests are relayed to the resource manager. Any function the host does not support is indicated by leaving its function pointer NULL; client calls to an unsupported operation return a “not supported” error. Passing NULL for module (or an empty structure) is permitted and indicates that the host will not support multi-node operations such as PMIx_Fence(3), but still intends to give local clients access to job information.
info: Pointer to an array of pmix_info_t(5) structures conveying directives that qualify server initialization (see DIRECTIVES). A NULL value is supported when no directives are desired.
ninfo: Number of elements in the info array.

18.2.245.3. DESCRIPTION

Initialize the PMIx server support library and register the host environment’s callback module. PMIx_server_init is called by the process that hosts the PMIx server — typically a resource manager daemon, launcher, or tool that will accept client and/or tool connections.

The PMIx server provides a function-shipping approach to the server side of the protocol: each client-visible PMIx operation is mirrored by an entry in the pmix_server_module_t structure. When a client request arrives, the PMIx server library invokes the corresponding host function so that resource managers can implement server behavior without being burdened with PMIx internal details. For performance and scalability, host module functions are required to return quickly and to execute their work asynchronously, completing each operation by invoking the callback function supplied to them.

Ownership rules for the module functions are important: all data passed to a host server function is owned by the PMIx server library and must not be freed by the host, while data returned by the host via a module callback is owned by the host and may be released once the callback returns.

The info array supplies additional information the server may need when initializing — for example, the namespace and rank to assign to the server itself, the temporary directory in which to place the rendezvous socket, or the PMIX_SERVER_TOOL_SUPPORT directive announcing that the daemon is willing to accept connection requests from tools (see DIRECTIVES).

The PMIx server library is reference counted. Repeated calls to PMIx_server_init are permitted and simply increment the reference count; if a module is provided on a later call and none had been set previously, the library adopts it. Each successful call must be balanced by a matching call to PMIx_server_finalize(3).

PMIx_server_init is a blocking call that completes synchronously; it does not take a callback.

18.2.245.4. DIRECTIVES

The following attributes are relevant to this operation. Support for any given attribute is optional and depends on how the PMIx implementation was built and on the capabilities of the host environment. All are passed in the info array.

18.2.245.4.1. Server identity and directories

PMIX_SERVER_NSPACE (char*) — namespace to assign to this PMIx server.
PMIX_SERVER_RANK (pmix_rank_t) — rank to assign to this PMIx server.
PMIX_SERVER_TMPDIR (char*) — temporary directory in which the server is to place client rendezvous points and contact information.
PMIX_SYSTEM_TMPDIR (char*) — temporary directory in which the server is to place tool rendezvous points and system-level contact information.

18.2.245.4.2. Role and support attributes

PMIX_SERVER_TOOL_SUPPORT (bool) — the host is willing to accept connection requests from tools.
PMIX_SERVER_SYSTEM_SUPPORT (bool) — the host is willing to accept connections from system-level tools (a system-level rendezvous point is established).
PMIX_SERVER_SESSION_SUPPORT (bool) — the host is willing to accept connections from session-level tools.
PMIX_SERVER_GATEWAY (bool) — the server is acting as a gateway that can relay operations (e.g., logging) requiring routing to other nodes.
PMIX_SERVER_SCHEDULER (bool) — the server is hosting the system scheduler (workload manager) and expects to receive scheduler-related requests.
PMIX_SERVER_SYS_CONTROLLER (bool) — the server is hosting the system controller.
PMIX_SERVER_REMOTE_CONNECTIONS (bool) — allow (or disable) connections from remote tools.
PMIX_SERVER_ALLOW_FOREIGN_TOOLS (bool) — mark the tool rendezvous files as readable by all users and allow tools running under user IDs other than that of the server to connect. The host retains ultimate authority over such connections and may restrict what foreign tools are permitted to do (for example, limiting them to queries) as dictated by host policy.
PMIX_ALLOW_CLIENT_CLONES (bool) — allow connections from clones (forks) of a registered client process.

18.2.245.4.3. Topology and behavior attributes

PMIX_TOPOLOGY2 (pmix_topology_t) — pointer to an implementation-specific description of the local node topology.
PMIX_SERVER_SHARE_TOPOLOGY (bool) — the server is to scalably expose the node topology to its local clients (for example, via shared-memory backing stores), cleaning up any artifacts at finalize.
PMIX_HOMOGENEOUS_SYSTEM (bool) — the nodes in the system are topologically identical, so the server need not compute or exchange per-node topology descriptions.
PMIX_SERVER_ENABLE_MONITORING (bool) — enable the internal monitoring capabilities of the PMIx server.
PMIX_EXTERNAL_PROGRESS (bool) — the host will progress the PMIx library as needed via calls to PMIx_Progress rather than PMIx spawning its own internal progress thread.
PMIX_SINGLETON (char*) — the server is operating in support of a singleton process; the value is the nspace.rank string of that singleton.
PMIX_IOF_LOCAL_OUTPUT (bool) — write output streams to the server’s own stdout/stderr.
PMIX_BIND_PROGRESS_THREAD (char*) — comma-delimited ranges of CPUs to which the internal PMIx progress thread is to be bound.
PMIX_BIND_REQUIRED (bool) — return an error if the internal PMIx progress thread cannot be bound as requested.
PMIX_EXTERNAL_AUX_EVENT_BASE (void*) — pointer to an event_base the library is to use for auxiliary functions (e.g., capturing signals) that would otherwise interfere with the host.

18.2.245.5. RETURN VALUE

Returns PMIX_SUCCESS on success. On error, a negative value corresponding to a PMIx error constant is returned, including:

PMIX_ERR_INIT — the PMIx server library could not be initialized (for example, a required transport was explicitly disabled, or a tight race between concurrent PMIx_server_init calls left the library in an unusable state).
PMIX_ERR_NOT_SUPPORTED — a provided directive requested behavior the implementation does not support.

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

18.2.245.6. NOTES

PMIx_server_init is intended for use only by processes acting as a PMIx server — processes that host the server support library on behalf of a resource manager or launcher. Client processes call PMIx_Init(3) and tools call PMIx_tool_init(3) instead.

After a successful PMIx_server_init, the host is expected to register each participating namespace with PMIx_server_register_nspace(3) and each local client with PMIx_server_register_client(3) before launching that client, then set up the client’s environment with PMIx_server_setup_fork.