19.2.5. PMIx_Put

PMIx_Put — Stage a key/value pair for distribution to other processes.

19.2.5.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Put(pmix_scope_t scope,
                       const char key[],
                       pmix_value_t *val);

19.2.5.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() ...
# the value is a Python ``pmix_value_t`` dictionary
rc = foo.put(PMIX_GLOBAL, "mykey",
             {'value': 42, 'val_type': PMIX_UINT32})

19.2.5.2. INPUT PARAMETERS

scope: A pmix_scope_t value describing the distribution scope of the posted data — i.e., which processes are to be able to access it (see SCOPE).
key: A NULL-terminated string identifying the value. The string must be no longer than PMIX_MAX_KEYLEN characters and must not begin with the reserved prefix "pmix".
val: Pointer to a pmix_value_t structure containing the value to be posted.

19.2.5.3. DESCRIPTION

Post a key-value pair for distribution. The provided value is copied into internal memory before PMIx_Put returns, so the caller may modify or free val immediately afterward. The client PMIx library caches the posted value locally until PMIx_Commit(3) is called, at which point the committed values are pushed to the local PMIx server, which distributes the data as directed by each value’s scope.

The pmix_value_t structure supports both string and binary values. PMIx implementations support heterogeneous environments by properly converting binary values between host architectures.

Note

Keys beginning with the string "pmix" are reserved for use by the PMIx Standard and the library. Applications must never use a defined PMIX_ attribute — or any other "pmix"-prefixed string — as the key in a call to PMIx_Put; doing so returns PMIX_ERR_BAD_PARAM.

19.2.5.4. SCOPE

The pmix_scope_t value passed as scope determines which processes are able to access the posted data. It is a uint8_t type taking one of the following values:

PMIX_LOCAL — the data is intended only for other application processes on the same node. It is not included in data packages sent to remote requesters.
PMIX_REMOTE — the data is intended solely for application processes on remote nodes. It is not shared with other processes on the same node.
PMIX_GLOBAL — the data is to be shared with all other requesting processes, regardless of location.
PMIX_INTERNAL — the data is intended solely for this process and is not shared with any other process. Typically used to cache data the process obtained by means outside of PMIx.

This implementation supports four additional values — PMIX_DEL_LOCAL, PMIX_DEL_REMOTE, PMIX_DEL_GLOBAL and PMIX_DEL_INTERNAL — which name the same audiences as the four above but direct that key be removed rather than stored. val is ignored for these and may be NULL. Removing a key that was never stored is not an error: the caller asked for it to be absent, and it is. As with a store, the removal takes effect on the calling process immediately and reaches other processes through the usual PMIx_Commit(3) and exchange path, so a PMIX_DEL_INTERNAL — which was never shared — is complete on return.

A specific implementation may support additional scope values, but all implementations support at least PMIX_GLOBAL. If a specified scope value is not supported, PMIx_Put returns PMIX_ERR_NOT_SUPPORTED. That is what a delete scope returns here when the local PMIx server is too old to act on it, which is checked up front rather than left to fail silently at the server.

19.2.5.5. RETURN VALUE

Returns PMIX_SUCCESS on success. On error, a negative value corresponding to a PMIx error constant is returned, including:

PMIX_ERR_BAD_PARAM — the key is NULL, exceeds PMIX_MAX_KEYLEN, or uses the reserved "pmix" prefix.
PMIX_ERR_NOT_SUPPORTED — the requested scope is not supported by the implementation.
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.5.6. NOTES

PMIx_Put only stages data locally; the values are not made available to other processes until they are committed with PMIx_Commit(3) and, typically, a subsequent synchronization such as PMIx_Fence(3) has completed.

Posting a new value under a key already published is permitted, but note that peers which have already retrieved that key will continue to see the earlier value: retrieved data is cached locally, and a later exchange does not by itself invalidate it. Such a peer must ask for the update with PMIX_GET_REFRESH_CACHE — see PMIx_Get(3).

Deleting a key. The removal requested by a PMIX_DEL_* scope is applied to the calling process at once. The local PMIx server, and every other client of that server that had already been handed the key, are corrected when the removal is committed with PMIx_Commit(3); the server tells them with a one-way notification that carries no acknowledgement, so that correction arrives promptly rather than synchronously and a peer that races it can see the old value once more. Processes on other nodes stop seeing the key at the next collecting PMIx_Fence(3) — the exchange is additive, so the removal has to be stated there, and a barrier-only fence does not carry it.

Within a single commit interval the server applies the removals before the values published alongside them, so a key that is deleted and then posted again before the next PMIx_Commit ends up present, while one that is posted and then deleted ends up absent.

Qualified values. A value may be posted together with one or more qualifiers that scope its later retrieval by using the reserved key PMIX_QUALIFIED_VALUE. In that case val must be a pmix_value_t of type PMIX_DATA_ARRAY whose first element is the primary key-value pair and whose remaining elements are the qualifier key-value pairs. The stored value is later obtained with PMIx_Get(3) by supplying the matching qualifiers, allowing several distinct values to be posted under the same key.

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