19.2.250. PMIx_server_deregister_client

PMIx_server_deregister_client — Deregister a local client and purge all data relating to it.

19.2.250.1. SYNOPSIS

#include <pmix_server.h>

void PMIx_server_deregister_client(const pmix_proc_t *proc,
                                   pmix_op_cbfunc_t cbfunc, void *cbdata);

19.2.250.1.1. Python Syntax

from pmix import *

foo = PMIxServer()
# ... after registering the client ...
foo.deregister_client({'nspace': "myjob", 'rank': 0})

19.2.250.2. INPUT PARAMETERS

proc: Pointer to a pmix_proc_t(5) structure identifying the client by namespace and rank.
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.

19.2.250.3. DESCRIPTION

Deregister the specified client and purge all data relating to it from the PMIx server library.

This API is intended primarily for exception cases. In normal operation, PMIx_server_deregister_nspace(3) deletes all client information for a namespace, and the PMIx server library automatically performs that cleanup once all local clients of a namespace have disconnected. PMIx_server_deregister_client is therefore needed only when a single client must be removed while its namespace remains active — though it may be called in non-exception cases if desired.

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 immediately, with cbfunc invoked once the client has been removed.
When cbfunc is NULL, the call is blocking: the function does not return until the deregistration is complete.

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

19.2.250.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 purged. status is PMIX_SUCCESS on success (including the case in which the named client or namespace was not found, which is treated as nothing to do). The callback (if provided) is instead invoked with PMIX_ERR_INIT if the PMIx server library was never initialized, with PMIX_ERR_NOT_AVAILABLE if its progress engine has already been stopped, with PMIX_ERR_BAD_PARAM if proc is NULL or names an empty namespace, and with PMIX_ERR_NOMEM if memory for the request could not be allocated. cbdata is the opaque pointer passed to PMIx_server_deregister_client.

19.2.250.5. NOTES

If the PMIx server library’s progress engine has already been stopped (for example, during finalize), the request cannot be serviced; any provided cbfunc is invoked with PMIX_ERR_NOT_AVAILABLE. This function reports no status of its own, so the callback is the only way a caller can be told, and a caller that was given one and never heard back would wait forever.

19.2.250.6. 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_client has no return value, so it cannot report PMIX_ERR_WOULD_BLOCK. When it is passed a NULL cbfunc from the progress thread it therefore completes the deregistration asynchronously on that same loop rather than refusing it. Nothing observable is lost: every other PMIx operation is serialized through that loop, so each will see the client gone exactly as it would have. Running the handler inline is not an option — it releases peers, and the up-call the caller is nested inside may still be holding one.