19.2.274. PMIx_tool_get_servers

PMIx_tool_get_servers — Return the process identifiers of all servers to which a tool is currently connected.

19.2.274.1. SYNOPSIS

#include <pmix_tool.h>

pmix_status_t PMIx_tool_get_servers(pmix_proc_t *servers[],
                                    size_t *nservers);

19.2.274.1.1. Python Syntax

from pmix import *

foo = PMIxTool()
rc, myname = foo.init(None)
# ... attach to one or more servers ...
rc, servers = foo.get_servers()
# servers is a list of {'nspace':..., 'rank':...} dictionaries

19.2.274.2. OUTPUT PARAMETERS

servers: Address at which the pointer to a newly allocated array of pmix_proc_t(5) structures is returned, one entry per connected server. The tool’s current primary (active) server, if any, is placed at the front of the array.
nservers: Address at which the number of elements in the returned servers array is stored.

19.2.274.3. DESCRIPTION

Obtain the set of PMIx servers to which the tool currently holds a connection. On success the routine allocates an array of pmix_proc_t(5) structures and returns its address and element count through the two output parameters. If the tool has an active primary server, that server’s identifier is returned as the first element of the array.

This is a blocking call: internally the request is thread-shifted onto the progress thread, which walks the tool’s list of server connections and builds the returned array.

19.2.274.4. RETURN VALUE

Returns PMIX_SUCCESS and a non-empty array when the tool is connected to at least one server. On error, a negative value corresponding to a PMIx error constant is returned, including:

PMIX_ERR_INIT — the tool library has not been initialized.
PMIX_ERR_NOT_AVAILABLE — the internal progress thread has been stopped, so the operation cannot be serviced.
PMIX_ERR_UNREACH — the tool is not currently connected to any server; in this case no array is returned and nservers is set to zero.

Other negative values indicate an appropriate error condition. PMIx error constants are defined in pmix_common.h.

19.2.274.5. NOTES

The caller assumes ownership of the returned servers array and is responsible for releasing it. In C, the array is allocated with the PMIx allocation macros and should be freed with PMIX_PROC_FREE(servers, nservers); the Python binding returns an ordinary list and frees the underlying array automatically.

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