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_MAXis not a valid session identifier.cbfunc: Callback function of type pmix_op_cbfunc_t invoked when the deregistration completes. ANULLvalue makes the call blocking (see DESCRIPTION).cbdata: Opaque pointer that is passed, unmodified, tocbfunc.
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
cbfuncis non-NULL, the call is non-blocking: it returns at once, andcbfuncis invoked when the session has been deregistered.When
cbfuncisNULL, 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.