19.2.4. PMIx_Finalize

PMIx_Finalize — Finalize the PMIx client library.

19.2.4.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Finalize(const pmix_info_t info[], size_t ninfo);

19.2.4.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() ...
# the directives is a list of Python ``pmix_info_t`` dictionaries
pydirs = [{'key': PMIX_EMBED_BARRIER,
           'value': True, 'val_type': PMIX_BOOL}]
rc = foo.finalize(pydirs)

19.2.4.2. INPUT PARAMETERS

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.

19.2.4.3. DESCRIPTION

Finalize the PMIx client, closing the connection with the local PMIx server. An error code is returned if, for some reason, the connection cannot be closed.

Because the PMIx client library is reference counted (see PMIx_Init(3)), PMIx_Finalize decrements the library reference count. Each call to PMIx_Init must be balanced with a matching call to PMIx_Finalize. Only when the reference count reaches zero — i.e., on the call that balances the first PMIx_Init — does the library actually finalize the client, close the connection to the local server, and release all internally allocated memory. Intermediate calls simply decrement the count and return PMIX_SUCCESS.

By default, PMIx_Finalize does not include an internal barrier operation: it returns as soon as the local bookkeeping and (on the final call) the server-side termination handshake are complete. Callers that require all participating processes to synchronize before disconnecting may request an embedded barrier via the PMIX_EMBED_BARRIER directive (see DIRECTIVES).

19.2.4.4. DIRECTIVES

The following attribute is relevant to this operation. Support for it is optional and depends on how the PMIx implementation was built.

PMIX_EMBED_BARRIER (bool) — execute a blocking fence operation across the caller’s namespace as part of the finalize operation. PMIx_Finalize performs no internal barrier by default; setting this attribute to true directs it to run the equivalent of a PMIx_Fence(3) over the caller’s namespace before disconnecting from the local server.

19.2.4.5. RETURN VALUE

Returns PMIX_SUCCESS on success, including on intermediate calls that only decrement the reference count. On error, a negative value corresponding to a PMIx error constant is returned, including:

PMIX_ERR_INIT — the PMIx library has not been initialized, so there is nothing to finalize.

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

19.2.4.6. NOTES

PMIx_Finalize is the counterpart to PMIx_Init(3) and is intended for use by client processes. Processes that initialized as tools should instead call PMIx_tool_finalize, and processes hosting a PMIx server should call PMIx_server_finalize.

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