25.2.252. PMIx_server_register_session

PMIx_server_register_session — Register a session and its session-level information with the PMIx server library.

25.2.252.1. SYNOPSIS

#include <pmix_server.h>

pmix_status_t PMIx_server_register_session(uint32_t sessionID,
                                           pmix_info_t info[], size_t ninfo,
                                           pmix_op_cbfunc_t cbfunc, void *cbdata);

25.2.252.2. INPUT PARAMETERS

  • sessionID: The session’s identifier, as the workload manager assigned it. UINT32_MAX is not a valid session identifier.

  • info: Array of pmix_info_t structures describing the session - the session-realm information its jobs’ processes can retrieve with PMIx_Get(3), such as PMIX_UNIV_SIZE and PMIX_MAX_PROCS (see the session-realm list in PMIx_server_register_nspace(3)). May be NULL.

  • ninfo: Number of elements in info.

  • 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.252.3. DESCRIPTION

Establish a session with the PMIx server library, and record its description.

A session is a set of resources the workload manager has assigned to one or more users. Jobs run within it and come and go; the session persists. A host can also establish a session by including a PMIX_SESSION_INFO_ARRAY in a job’s registration (PMIx_server_register_nspace(3)): a job that names a session the library does not know establishes it. That still works. This call says so directly, and is the way to:

  • describe a session before its first job is registered;

  • keep a session after its last job is deregistered. A session established only by its jobs has no existence apart from them.

Registering a session with no info still establishes it: a job registered later in that session finds this one rather than creating another.

Registering a session that is already known updates it. The keys the new registration gives replace the ones the library holds; keys it does not mention are kept. A session’s resources change while it runs (it is extended, or a node is lost), and this is how the host says so. Clients that are already running are told of the change, and read the new values on their next PMIx_Get. A registration that restates what the library already holds changes nothing.

The call thread-shifts the request onto the library’s progress thread. It supports a non-blocking and a blocking mode, selected by cbfunc:

  • When cbfunc is non-NULL, the call is non-blocking: it returns PMIX_SUCCESS at once, and cbfunc is invoked when the session has been registered. The caller must keep info valid until then.

  • When cbfunc is NULL, the call is blocking: it returns when the registration is complete, with its result.

25.2.252.4. RETURN VALUE

  • PMIX_SUCCESS — for a non-blocking call, the request was accepted and the result will be delivered to cbfunc; for a blocking call, the session was registered.

  • PMIX_ERR_INIT — the PMIx server library is not initialized.

  • PMIX_ERR_NOT_AVAILABLE — the library’s progress engine has already been stopped.

  • PMIX_ERR_BAD_PARAM — sessionID is UINT32_MAX.

  • PMIX_ERR_NOMEM — the request could not be allocated.

Other negative values report a failure to record the session’s information.

25.2.252.5. 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 it from its progress thread once the session has been registered. status is PMIX_SUCCESS on success, or a negative PMIx error constant otherwise.

25.2.252.6. NOTES

A session registered here is removed only by PMIx_server_deregister_session(3). The library cannot tell when a session has ended: a session with no job running is an ordinary state.

25.2.252.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.

Exception for this call. When PMIx_server_register_session is passed a NULL cbfunc from the progress thread - from inside one of the host’s up-calls - it does not return PMIX_ERR_WOULD_BLOCK. It completes the registration asynchronously on that same loop and returns PMIX_SUCCESS. Every other PMIx operation is serialized through that loop, so each sees the session registered exactly as it would have.