19.2.11. PMIx_Unpublish

PMIx_Unpublish, PMIx_Unpublish_nb — Remove data previously posted via PMIx_Publish(3).

19.2.11.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Unpublish(char **keys,
                             const pmix_info_t info[], size_t ninfo);

pmix_status_t PMIx_Unpublish_nb(char **keys,
                                const pmix_info_t info[], size_t ninfo,
                                pmix_op_cbfunc_t cbfunc, void *cbdata);

19.2.11.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() ...
# pykeys is a list of key strings to remove (None removes all)
pykeys = ["mykey"]
# directives is a list of Python ``pmix_info_t`` dictionaries
pydirs = [{'key': PMIX_RANGE,
           'value': PMIX_RANGE_SESSION, 'val_type': PMIX_UINT8}]
rc = foo.unpublish(pykeys, pydirs)

# the non-blocking form returns as soon as the request has been accepted
# and reports the result by executing a callback on the PMIx progress
# thread. The callback is run if and only if the call returned
# PMIX_SUCCESS, and must not itself make a blocking PMIx call.
def donecb(status, cbdata):
    print("unpublish completed:", foo.error_string(status))
rc = foo.unpublish_nb(pykeys, pydirs, donecb, "mycbdata")

19.2.11.2. INPUT PARAMETERS

keys: A NULL-terminated array of key strings identifying the published data to remove. A NULL value instructs the server to remove all data published by the calling process.
info: Pointer to an array of pmix_info_t(5) structures conveying directives that qualify the operation (see DIRECTIVES). A NULL value is supported when no directives are desired.
ninfo: Number of elements in the info array.

The non-blocking form adds a callback:

cbfunc: Callback function of type pmix_op_cbfunc_t invoked once the server confirms removal of the specified data.
cbdata: Opaque pointer that is passed, unmodified, to cbfunc.

19.2.11.3. DESCRIPTION

Remove data previously posted by this process with PMIx_Publish(3), using the provided keys. A NULL keys array removes all data published by the calling process within the specified range.

By default, the range is assumed to be PMIX_RANGE_SESSION. That default, and any additional directives, may be changed by including the appropriate attributes in the info array. The range supplied here must match the range under which the data was published.

PMIx_Unpublish is the blocking form: it does not return until the server has confirmed removal of the data — after which it is safe to publish the same key again within the specified range. PMIx_Unpublish_nb is the non-blocking form: it returns immediately and invokes cbfunc once the server confirms removal. As with all non-blocking PMIx APIs, the caller must keep the keys and info arrays valid until cbfunc is invoked.

The PMIx library automatically adds the requesting process’s PMIX_USERID and PMIX_GRPID to the information passed to the host environment; a process can only unpublish data that it published.

19.2.11.4. DIRECTIVES

The following attributes qualify this operation. PMIx libraries are not required to support any of them directly, but must pass any that are provided to the host environment; where supported, they are optional for host environments.

PMIX_RANGE (pmix_data_range_t) — the range from which the data is to be removed (e.g., PMIX_RANGE_SESSION, PMIX_RANGE_NAMESPACE, PMIX_RANGE_GLOBAL). Must match the range under which the data was published. Defaults to PMIX_RANGE_SESSION.
PMIX_TIMEOUT (int) — maximum time, in seconds, for the operation to complete before returning an error (0 => infinite).

19.2.11.5. RETURN VALUE

For the blocking form, PMIX_SUCCESS indicates that the specified data has been removed. For the non-blocking form, a return of PMIX_SUCCESS indicates only that the request was accepted for processing; the final status is delivered to cbfunc. A non-blocking call may instead return PMIX_OPERATION_SUCCEEDED to indicate that the request was immediately processed and succeeded, in which case cbfunc will not be called.

PMIX_SUCCESS — the specified data has been removed.
PMIX_ERR_UNREACH — the local PMIx server could not be reached.
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.11.6. NOTES

Unpublishing is scoped to the publishing process and to the specified range: a process cannot remove data published by another process, and the range supplied must match the one used at publication time. After a successful unpublish, the same key may be published again within that range.

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