25.2.278. PMIx_tool_finalize
PMIx_tool_finalize — Finalize the PMIx tool library.
25.2.278.1. SYNOPSIS
#include <pmix_tool.h>
pmix_status_t PMIx_tool_finalize(void);
25.2.278.1.1. Python Syntax
from pmix import *
foo = PMIxTool()
rc, myname = foo.init(None)
# ... use the tool ...
rc = foo.finalize()
25.2.278.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 bounded by the pmix_tool_finalize_timeout parameter (5 seconds by
default), 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.
25.2.278.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.
25.2.278.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.PMIX_ERR_WOULD_BLOCK—PMIx_tool_finalizewas called from within a PMIx event handler or callback. The teardown waits on the PMIx progress thread and then stops it, which from that thread would be the thread waiting on itself. Nothing was finalized, and the call may be repeated from another thread.PMIX_ERR_TIMEOUT— the server did not answer the finalize handshake in time.
Other negative values indicate a failure to cleanly complete the finalize
handshake with the server: the host’s answer to it, or a failure to send it. A
host that does not implement the client_finalized up-call is not a failure,
nor is a server that closes the connection in answer instead of replying.
In every case but PMIX_ERR_INIT and PMIX_ERR_WOULD_BLOCK the library is
finalized. PMIx error constants are defined in pmix_common.h.
25.2.278.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).