25.2.253. PMIx_server_deregister_session

PMIx_server_deregister_session — Deregister a session and release the information held for it.

25.2.253.1. SYNOPSIS

#include <pmix_server.h>

void PMIx_server_deregister_session(uint32_t sessionID,
                                    pmix_op_cbfunc_t cbfunc, void *cbdata);

25.2.253.2. INPUT PARAMETERS

  • sessionID: The identifier of the session to deregister. UINT32_MAX is not a valid session identifier.

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

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

25.2.253.3. DESCRIPTION

Tell the PMIx server library that a session has ended, so that it can release the information it holds for it. This is the session-level counterpart of PMIx_server_deregister_nspace(3).

The host must say so: the library cannot infer that a session is over when its last job is deregistered, since a session with no job running is an ordinary state and another job may be about to start in it.

Jobs in the session are not deregistered by this call. The host deregisters them with PMIx_server_deregister_nspace(3), before or after this call. A job still registered keeps the session’s information available to its processes until it is deregistered, so the two may be done in either order.

Deregistering a session this server never knew is not an error. A host may deregister a session on every node, including nodes where none of its jobs ran.

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 at once, and cbfunc is invoked when the session has been deregistered.

  • When cbfunc is NULL, the call is blocking: it returns when the deregistration is complete.

Because the function returns void, a caller that needs to know the outcome must supply a cbfunc and inspect the status delivered to it.

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

status is PMIX_SUCCESS on success, or a negative PMIx error constant otherwise. In particular, the callback is invoked with PMIX_ERR_INIT if the PMIx server library is not initialized, with PMIX_ERR_NOT_AVAILABLE if its progress engine has already been stopped, with PMIX_ERR_BAD_PARAM if sessionID is UINT32_MAX, and with PMIX_ERR_NOMEM if the request could not be allocated.

25.2.253.5. 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. PMIx_server_deregister_session has no return value, so it cannot report PMIX_ERR_WOULD_BLOCK. When it is passed a NULL cbfunc from the progress thread it completes the deregistration asynchronously on that same loop. Every other PMIx operation is serialized through that loop, so each sees the session gone exactly as it would have.