25.2.254. PMIx_server_register_client

PMIx_server_register_client — Register a local client process with the PMIx server library.

25.2.254.1. SYNOPSIS

#include <pmix_server.h>

pmix_status_t PMIx_server_register_client(const pmix_proc_t *proc,
                                          uid_t uid, gid_t gid,
                                          void *server_object,
                                          pmix_op_cbfunc_t cbfunc, void *cbdata);

25.2.254.1.1. Python Syntax

from pmix import *

foo = PMIxServer()
# ... after registering the namespace ...
rc = foo.register_client({'nspace': "myjob", 'rank': 0}, 1000, 1000)

25.2.254.2. INPUT PARAMETERS

  • proc: Pointer to a pmix_proc_t(5) structure identifying the client by namespace and rank.

  • uid: The expected user ID of the child process.

  • gid: The expected group ID of the child process.

  • server_object: An optional opaque pointer the host wishes to associate with this client. If provided, the library returns it to the host whenever a server-module function is invoked in relation to this specific process, letting the host access its tracking object without a namespace/rank lookup. May be NULL.

  • cbfunc: Callback function of type pmix_op_cbfunc_t invoked when the registration completes. A NULL value makes the call blocking (see DESCRIPTION).

  • cbdata: Opaque pointer that is passed, unmodified, to cbfunc.

25.2.254.3. DESCRIPTION

Register a local client process with the PMIx server library. The host resource manager is required to execute this operation prior to starting the client process, so that the library is prepared for the connection the client will make when it calls PMIx_Init(3).

The expected uid and gid allow the server library to authenticate a client as it connects by requiring the detected user and group IDs of the connecting process to match the registered values. Because this check is performed at registration time, the detected user and group IDs are not passed to the host again in the pmix_server_client_connected2_fn_t server module function.

The optional server_object provides a convenience for the host: any object passed here is handed back to the host in subsequent server-module callbacks that pertain to this client (for example, client_connected2 or client_finalized), allowing the host to track per-client state without an internal lookup.

Like other server registration APIs, this call thread-shifts the request onto the library’s internal progress thread and supports both a non-blocking and a blocking mode, selected by the cbfunc argument:

  • When cbfunc is non-NULL, the call is non-blocking: the request is posted to the progress thread and the function returns PMIX_SUCCESS immediately, with cbfunc invoked once the client has been registered.

  • When cbfunc is NULL, the call is blocking: the function does not return until registration is complete, and on success returns PMIX_OPERATION_SUCCEEDED.

25.2.254.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);

The library invokes cbfunc from its progress thread once the client has been registered. status is PMIX_SUCCESS on success, PMIX_UPDATED when the rank was already registered and has been updated (also a success), or a negative PMIx error constant otherwise. cbdata is the opaque pointer passed to PMIx_server_register_client.

25.2.254.5. 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 to cbfunc.

For the blocking form (cbfunc is NULL), the return value carries the result directly:

  • PMIX_OPERATION_SUCCEEDED — the client was registered successfully inline; no callback is or will be invoked.

  • 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 registration.

  • PMIX_ERR_BAD_PARAM — proc is NULL or names an empty namespace.

  • PMIX_UPDATED — the host had already registered the rank, and it has been updated: the uid, gid and server_object given here replace the ones it had. This is a success, not an error. The first registration of a rank the library made an entry for itself - the singleton named by PMIX_SINGLETON - returns PMIX_SUCCESS.

  • PMIX_ERR_EXISTS — the rank is already registered, a process is connected as it (or is being accepted on it), and that process’s uid or gid is not the one given here. Nothing is changed.

  • PMIX_ERR_NOT_SUPPORTED — the namespace belongs to a self-started tool. A namespace holds either processes the host started (clients and tool-clients) or self-started tools, never both. Registering the namespace in full with PMIx_server_register_nspace(3) first takes the name back.

  • PMIX_ERR_WOULD_BLOCK — the blocking form was called from the library’s own progress thread. See PROGRESS THREAD RESTRICTION.

PMIX_ERR_INIT, PMIX_ERR_NOT_AVAILABLE, PMIX_ERR_BAD_PARAM and PMIX_ERR_NOMEM are returned directly by both forms, since they are detected before the request is accepted.

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

25.2.254.6. NOTES

There is no requirement that the namespace be registered before its clients. If the namespace named in proc has not yet been registered, the library creates a placeholder namespace and appends this client to it, in anticipation of an eventual PMIx_server_register_nspace(3) call. The namespace must be registered before the client is started, though: a client that connects while its namespace is only a placeholder is refused (PMIX_ERR_INVALID_CRED). After registering the client, the host must call PMIx_server_setup_fork to inject the environment the client needs to connect back to this server.

From registration on, a process of this release that connects as the rank must present the token PMIx_server_setup_fork hands out for it, and is refused with PMIX_ERR_INVALID_CRED until then: registration keeps a token for the rank that nobody is handed. A host may also call the two functions in the other order. The exception is the singleton named by PMIX_SINGLETON when the server was initialized, which this server registered itself: it was not prepared, so no token is asked of it. The registration takes its rank over only for the uid and gid of the connection that holds it: for any other it returns PMIX_ERR_EXISTS.

Registering a rank the host has already registered updates it: the new uid, gid and server_object replace the old ones, and the call returns PMIX_UPDATED. A host uses this to re-register a process it restarts. The rank keeps the connection token already handed out for it. An update never adds a second entry for the rank, so the namespace’s count of local processes is not disturbed. Per-process data such as binding and locality is updated with PMIx_server_register_nspace(3) instead, as an update (negative nlocalprocs).

A process that was not registered cannot connect as a client or as a tool-client (a tool the host starts, which is registered with this function in the same way). Any process that connects as this namespace and rank must have the uid and gid registered here, and only one may be connected as it at a time. A registration lasts until the host calls PMIx_server_deregister_client(3) or PMIx_server_deregister_nspace(3) — a client that finalizes, or exits, does not end it.

25.2.254.7. PROGRESS THREAD RESTRICTION

A blocking PMIx call must not be made from within the PMIx progress thread. Any code the library itself invokes runs on that thread: an event handler registered through PMIx_Register_event_handler(3), a callback passed to a non-blocking PMIx API, and — in a server or tool — the completion of a host-module up-call. A blocking call waits for work that the progress thread has to perform, so making one from that thread waits for itself and never returns. The PMIx Standard disallows it, and there is no way for an implementation to service such a request.

Where this call has a blocking form — including the blocking behavior a non-blocking entry point adopts when it is passed a NULL cbfunc — that form detects the situation and returns PMIX_ERR_WOULD_BLOCK immediately, accompanied by a diagnostic naming the call. Nothing is done and no callback is invoked.

PMIX_ERR_WOULD_BLOCK here is not a transient condition to retry: it reports a call that cannot be serviced from where it was made. Reissue it as the non-blocking form with a callback, or from a thread of your own.