18.2.5. PMIx_Put

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

18.2.5.1. SYNOPSIS

#include <pmix.h>

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

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

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

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

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

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.

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

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

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.