19.2.6. PMIx_Commit

PMIx_Commit — Make previously staged key/value pairs available to other processes.

19.2.6.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Commit(void);

19.2.6.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after one or more foo.put() calls ...
rc = foo.commit()

19.2.6.2. DESCRIPTION

Make available to other processes all key-value pairs previously staged by this process via PMIx_Put(3).

A PMIx implementation may locally cache non-reserved keys in the client library until they are committed. PMIx_Commit initiates the operation of making those staged key-value pairs available; depending on the implementation, this may involve transmitting the entire collection of data posted by the process to the local PMIx server. In this implementation the call returns once the local server has received and acknowledged the data — which is not the same as the data being available to peers, as the note below explains.

Only what changed is sent. This implementation ordinarily transmits just what has been posted since the previous PMIx_Commit, falling back to the entire collection where that is not sufficient — for instance when a qualified value is involved (it is stored under the reserved PMIX_QUALIFIED_VALUE key, so there is no key to ask for it back by), or on the first commit made to a server that has not seen anything this process published, such as after a tool repoints at another server. Either way the effect on the caller is the same, and a key posted more than once between two commits is transmitted once, carrying the value it had when PMIx_Commit was called. The saving matters because the older behavior re-sent everything published so far on every call, so n put/commit cycles moved O(n²) bytes.

Deletions are carried too. A key removed by one of the PMIX_DEL_* scopes of PMIx_Put(3) cannot simply be left out of the next transmission — the server accumulates what it is sent, so omitting a key removes nothing. The removals requested since the previous commit are therefore stated explicitly, and are applied by the server ahead of the values sent with them; see the discussion of ordering in PMIx_Put(3). A commit that carries a removal sends the full collection rather than a delta, since the record a delta is built from names keys to be fetched back and a deleted key is precisely the one that will not be found. Passing the removal on to the other nodes is the collecting PMIx_Fence(3)’s business, not the commit’s.

Note

Users are advised to always include the call to PMIx_Commit in case the local implementation requires it. Committing does not by itself circulate the posted data to other processes: availability of the data to peers still relies on the exchange mechanisms — typically a synchronization such as PMIx_Fence(3) — that govern data sharing.

PMIx_Commit takes no arguments. As a convenience, it is a no-op that returns PMIX_SUCCESS when there is nothing to commit — for example, when the caller is a singleton process with no local server to receive the data.

19.2.6.3. RETURN VALUE

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

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.6.4. NOTES

Because commitment does not guarantee that peers can immediately retrieve the data, a typical publication sequence is one or more PMIx_Put(3) calls, followed by PMIx_Commit, followed by a collective synchronization such as PMIx_Fence(3) before the peers issue PMIx_Get(3).

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