18.2.11. PMIx_Unpublish

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

18.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);

18.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': {'value': PMIX_RANGE_SESSION, 'val_type': PMIX_UINT8}}]
rc = foo.unpublish(pykeys, pydirs)

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

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

18.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).

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

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