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 beNULL.cbfunc: Callback function of type pmix_op_cbfunc_t invoked when the registration completes. ANULLvalue makes the call blocking (see DESCRIPTION).cbdata: Opaque pointer that is passed, unmodified, tocbfunc.
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
cbfuncis non-NULL, the call is non-blocking: the request is posted to the progress thread and the function returnsPMIX_SUCCESSimmediately, withcbfuncinvoked once the client has been registered.When
cbfuncisNULL, the call is blocking: the function does not return until registration is complete, and on success returnsPMIX_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—procisNULLor names an empty namespace.PMIX_UPDATED— the host had already registered the rank, and it has been updated: theuid,gidandserver_objectgiven 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 byPMIX_SINGLETON- returnsPMIX_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.