18.2.270. PMIx_tool_finalize

PMIx_tool_finalize — Finalize the PMIx tool library.

18.2.270.1. SYNOPSIS

#include <pmix_tool.h>

pmix_status_t PMIx_tool_finalize(void);

18.2.270.1.1. Python Syntax

from pmix import *

foo = PMIxTool()
rc, myname = foo.init(None)
# ... use the tool ...
rc = foo.finalize()

18.2.270.2. DESCRIPTION

Finalize the PMIx tool library, closing any open connection to a PMIx server and releasing the resources allocated by PMIx_tool_init(3). An error code is returned if, for some reason, the connection cannot be cleanly closed.

If the tool is currently connected to a server, PMIx_tool_finalize sends a finalize synchronization to that server and waits for the acknowledgment. This wait is protected by an internal timeout so the call cannot block indefinitely should the server become unresponsive. Any output still buffered for the tool’s local stdout/stderr sinks is flushed before those sinks are torn down.

If the tool was acting as a launcher or server, any children it started are cleanly terminated before the progress thread is stopped and the server-side infrastructure is released.

18.2.270.2.1. Reference counting

Because PMIx_tool_init(3) is reference counted, a tool that initialized the library more than once must call PMIx_tool_finalize a matching number of times. Only the final call — the one that drops the reference count to zero — actually tears the library down; earlier calls simply decrement the count and return PMIX_SUCCESS. The one-time-init latch is reset by the final finalize, so a subsequent PMIx_tool_init in the same process starts a fresh library instance.

This is a blocking call.

18.2.270.3. RETURN VALUE

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

PMIX_ERR_INIT — the PMIx tool library was not initialized, so there is nothing to finalize.

Other negative values indicate a failure to cleanly complete the finalize handshake with the server. PMIx error constants are defined in pmix_common.h.

18.2.270.4. NOTES

PMIx_tool_finalize must only be called by processes that initialized via PMIx_tool_init(3). Client processes must instead call PMIx_Finalize(3), and server processes must call PMIx_server_finalize(3).