18.2.271. PMIx_tool_attach_to_server

PMIx_tool_attach_to_server — Establish a connection from a tool to a PMIx server.

18.2.271.1. SYNOPSIS

#include <pmix_tool.h>

pmix_status_t PMIx_tool_attach_to_server(pmix_proc_t *myproc,
                                         pmix_proc_t *server,
                                         pmix_info_t info[], size_t ninfo);

18.2.271.1.1. Python Syntax

from pmix import *

foo = PMIxTool()
rc, myname = foo.init(None)
# the directives is a list of Python ``pmix_info_t`` dictionaries
pydirs = [{'key': PMIX_CONNECT_TO_SYSTEM,
           'value': {'value': True, 'val_type': PMIX_BOOL}}]
rc, myname, mysrvr = foo.attach_to_server(pydirs)

18.2.271.2. INPUT PARAMETERS

info: Pointer to an array of pmix_info_t(5) structures identifying the target server and qualifying the connection (see DIRECTIVES). Passing a NULL value for the info array pointer, or a zero ninfo, is not allowed and results in return of PMIX_ERR_BAD_PARAM.
ninfo: Number of elements in the info array.

18.2.271.3. OUTPUT PARAMETERS

myproc: Pointer to a pmix_proc_t(5) structure in which the tool’s own namespace and rank are returned. PMIx does not currently support on-the-fly changes to the tool’s identifier, so this is filled with the tool’s existing identity; NULL may be passed if it is not required.
server: Pointer to a pmix_proc_t(5) structure in which the identifier of the server that was attached is returned. NULL may be passed if the server’s identity is not required.

18.2.271.4. DESCRIPTION

Establish a connection from an already-initialized tool to a PMIx server. The target server is identified by one of the attributes in the info array (see DIRECTIVES).

This routine replaces the older PMIx_tool_connect_to_server entry point, adding the ability to return the identifier of the server to which the tool attached via the server output parameter.

By default, attaching to a server registers the connection but does not change the tool’s primary server — the one used for subsequent operations. To make the newly attached server the primary (and mark the tool as connected), include the PMIX_PRIMARY_SERVER attribute in the info array.

Note

PMIx does not currently support on-the-fly changes to the tool’s identifier. The new server must therefore be under the same namespace manager (e.g., the same host resource manager) as any prior server, so that the tool’s original namespace remains a unique assignment. The myproc parameter is provided for obsolescence protection in case this constraint is ever removed; for now it is simply filled with the tool’s existing namespace and rank.

This is a blocking call: internally the request is thread-shifted onto the progress thread, and the caller waits for the connection attempt to complete before the routine returns.

18.2.271.5. DIRECTIVES

The following attributes are relevant to this operation. At least one server- identifying attribute must be supplied.

18.2.271.5.1. Target server attributes

PMIX_CONNECT_TO_SYSTEM (bool) — connect solely to the system-level PMIx server.
PMIX_CONNECT_SYSTEM_FIRST (bool) — preferentially look for a system-level PMIx server first, and then fall back to a server identified by another attribute.
PMIX_SERVER_URI (char*) — connect to the server at the given URI.
PMIX_SERVER_NSPACE (char*) — connect to the server of the given namespace.
PMIX_SERVER_PIDINFO (pid_t) — connect to the server embedded in the process with the given PID.
PMIX_TCP_URI (char*) — URI of the server to connect to, or a file name containing it in the form file:<name of file>.
PMIX_TOOL_ATTACHMENT_FILE (char*) — file containing the connection information to be used for attaching to the server.

18.2.271.5.2. Connection-control attributes

PMIX_PRIMARY_SERVER (bool) — designate the server being attached as the tool’s primary server. When set, the tool’s active server is switched to the new connection and the tool is marked as connected.
PMIX_TIMEOUT (int) — time, in seconds, to wait for the connection to be established before returning an error (0 implies no timeout).

18.2.271.6. RETURN VALUE

Returns PMIX_SUCCESS when the connection has been established. 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_BAD_PARAM — the info array was NULL or ninfo was zero, so no target server was specified.
PMIX_ERR_UNREACH — the specified server could not be reached.

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

18.2.271.7. NOTES

The tool must already have been initialized via PMIx_tool_init(3) before calling this routine. A tool may hold connections to multiple servers simultaneously; use PMIx_tool_get_servers(3) to enumerate them, PMIx_tool_set_server(3) to select the active server among them, and PMIx_tool_disconnect(3) to drop a connection.