18.2.279. PMIx_IOF_deregister

PMIx_IOF_deregister — Deregister from output previously requested via PMIx_IOF_pull.

18.2.279.1. SYNOPSIS

#include <pmix_tool.h>

pmix_status_t PMIx_IOF_deregister(size_t iofhdlr,
                                  const pmix_info_t directives[], size_t ndirs,
                                  pmix_op_cbfunc_t cbfunc, void *cbdata);

18.2.279.1.1. Python Syntax

from pmix import *

foo = PMIxTool()
# ... after a successful foo.iof_pull() that returned refid ...
pydirs = []
rc = foo.iof_deregister(refid, pydirs)

18.2.279.2. INPUT PARAMETERS

iofhdlr: The reference identifier returned from the earlier call to PMIx_IOF_pull(3) (delivered through that call’s registration callback, or as its blocking result) identifying the forwarding request to be canceled.
directives: Pointer to an array of pmix_info_t(5) structures conveying directives that control the behavior of the request — for example, directives regarding the disposition of any data currently in the I/O buffer for the affected processes. A NULL value is supported when no directives are desired.
ndirs: Number of elements in the directives array.
cbfunc: Callback function of type pmix_op_cbfunc_t invoked when deregistration has completed. A NULL value makes the call blocking (see DESCRIPTION).
cbdata: Opaque pointer passed, unmodified, to cbfunc.

18.2.279.3. DESCRIPTION

Cancel a forwarding request previously established with PMIx_IOF_pull(3). The request is thread-shifted onto the PMIx progress thread for processing.

When cbfunc is non-NULL the call is non-blocking: it returns immediately and the result is delivered later through cbfunc. When cbfunc is NULL the call is blocking and the result of the operation is carried in the return value.

Note that any I/O being flushed as a result of the deregistration may continue to be received after deregistration has completed. Implementations are advised to flush any currently buffered I/O upon receipt of the request, and to discard all I/O received after that point.

18.2.279.4. CALLBACK FUNCTION

When provided, cbfunc has the signature pmix_op_cbfunc_t:

typedef void (*pmix_op_cbfunc_t)(pmix_status_t status, void *cbdata);

It is invoked with the final status of the deregistration and the cbdata pointer that was supplied to PMIx_IOF_deregister.

18.2.279.5. RETURN VALUE

For the non-blocking form (cbfunc non-NULL), a return of PMIX_SUCCESS indicates only that the request was accepted for processing; the final status is delivered to cbfunc. A return of PMIX_OPERATION_SUCCEEDED indicates that the request was processed immediately and successfully, in which case cbfunc will not be called.

For the blocking form (cbfunc is NULL), the return value carries the result of the operation directly. Error constants that may be returned include:

PMIX_ERR_INIT — the PMIx library has not been initialized.
PMIX_ERR_NOT_AVAILABLE — the operation cannot be serviced because the library’s progress engine has been stopped.
PMIX_ERR_NOT_SUPPORTED — the calling process is a server (that is not also a launcher) and therefore cannot deregister I/O forwarding.
PMIX_ERR_UNREACH — the tool is not connected to a server.
PMIX_ERR_NOMEM — the library was unable to allocate memory for the request.

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

18.2.279.6. NOTES

The iofhdlr passed here must be the identifier returned by the matching PMIx_IOF_pull(3) request; passing an unknown identifier results in an error.