20.2.70. PMIx_Store_internal

PMIx_Store_internal — Store a key/value pair locally for retrieval within this process.

20.2.70.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Store_internal(const pmix_proc_t *proc,
                                  const char key[],
                                  pmix_value_t *val);

20.2.70.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() ...
# proc is a dict {'nspace': ..., 'rank': ...} or None for this process
# the value is a Python ``pmix_value_t`` dictionary
rc = foo.store_internal({'nspace': 'myapp', 'rank': 0}, "mykey",
                        {'value': 42, 'val_type': PMIX_UINT32})

20.2.70.2. INPUT PARAMETERS

proc: Pointer to a pmix_proc_t identifying the process (namespace and rank) under which the data is to be stored. If NULL, the calling process’s own identifier is used.
key: A NULL-terminated string identifying the value. The string must be no longer than PMIX_MAX_KEYLEN characters.
val: Pointer to a pmix_value_t structure containing the value to be stored.

20.2.70.3. DESCRIPTION

Store some data locally for retrieval by other areas of the process. This is data that has only internal scope — it will never be “pushed” or otherwise posted externally to other processes. It is typically used to cache data obtained by means outside of PMIx so that it can subsequently be accessed by various parts of the same process through PMIx_Get(3).

The value is copied into internal memory before PMIx_Store_internal returns, so the caller may modify or free val immediately afterward. Because the data is associated with the proc identifier, a later PMIx_Get(3) using that same identifier and key will retrieve the stored value.

Unlike PMIx_Put(3), whose data is staged for distribution to other processes, data stored with PMIx_Store_internal never leaves the process and requires no subsequent commit or synchronization step.

20.2.70.4. 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 or exceeds PMIX_MAX_KEYLEN characters.
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.
PMIX_ERR_NOMEM — the library was unable to allocate memory to store the data.

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

20.2.70.5. NOTES

Data stored with PMIx_Store_internal has purely internal scope; it is visible only within the storing process and is never shared with peers. To make data available to other processes, use PMIx_Put(3) followed by PMIx_Commit(3) instead.

Warning

A host environment must not use this call to revise a job’s data. It is sometimes reached for on a server because it appears to be a direct way to put a value where clients will find it. It is not, and the reason is worth being precise about: the value is stored in the calling process’s own datastore, which on a server is gds/hash, while the data a local client reads may live somewhere else entirely — the shared-memory segments of gds/shmem3, for instance. Nothing propagates the value to those, and no client is told anything happened. The result is a server whose own answer to a query differs from what its clients hold, with no error reported anywhere.

Job data is revised with PMIx_server_register_nspace(3), passing a negative nlocalprocs, which reaches every datastore holding that namespace and pushes the change to the clients already running.

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