19.2.33. PMIx_Deregister_event_handler

PMIx_Deregister_event_handler — Deregister a previously registered event handler.

19.2.33.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Deregister_event_handler(size_t evhdlr_ref,
                                            pmix_op_cbfunc_t cbfunc,
                                            void *cbdata);

19.2.33.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() and register_event_handler() ...
# refid is the reference identifier returned by registration
rc = foo.deregister_event_handler(refid)

19.2.33.2. INPUT PARAMETERS

evhdlr_ref: The reference identifier (a size_t) that was returned by the corresponding call to PMIx_Register_event_handler(3) when the handler was registered.
cbfunc: Callback function of type pmix_op_cbfunc_t to be 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.33.3. DESCRIPTION

Remove a previously registered event handler, identified by the reference identifier assigned to it at registration time.

If cbfunc is NULL the call is blocking: it does not return until the deregistration is complete, and the result of the operation is returned in the status code. If cbfunc is non-NULL the call is non-blocking: it returns immediately, and the provided cbfunc is invoked with the final status once the operation completes.

No event corresponding to the referenced registration is delivered once the deregistration operation has completed — that is, following return from the API with PMIX_OPERATION_SUCCEEDED or execution of cbfunc.

19.2.33.4. RETURN VALUE

For the blocking form, the return value carries the result of the operation. For the non-blocking form, a return of PMIX_SUCCESS indicates only that the request was accepted for processing and the final status will be delivered to cbfunc.

PMIX_SUCCESS — the handler was successfully deregistered.
PMIX_OPERATION_SUCCEEDED — (non-blocking form) the request was satisfied immediately and cbfunc will not be called.
PMIX_ERR_BAD_PARAM — the provided evhdlr_ref was not recognized.
PMIX_ERR_NOT_SUPPORTED — the PMIx implementation does not support event notification.
PMIX_ERR_NOT_AVAILABLE — the operation cannot be serviced because the library’s progress engine has been stopped.
PMIX_ERR_INIT — the PMIx library has not been initialized.

Any other negative value indicates an appropriate error condition. PMIx error constants are defined in pmix_common.h.

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