18.2.2. PMIx_Init

PMIx_Init — Initialize the PMIx client library.

18.2.2.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Init(pmix_proc_t *proc,
                        pmix_info_t info[], size_t ninfo);

18.2.2.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# the directives is a list of Python ``pmix_info_t`` dictionaries
pydirs = [{'key': PMIX_PROGRAMMING_MODEL,
           'value': {'value': "MPI", 'val_type': PMIX_STRING}}]
rc, myname = foo.init(pydirs)

18.2.2.2. INPUT PARAMETERS

info: Pointer to an array of pmix_info_t(5) structures conveying directives that qualify the initialization (see DIRECTIVES). A NULL value is supported when no directives are desired.
ninfo: Number of elements in the info array.

18.2.2.3. INPUT/OUTPUT PARAMETERS

proc: Pointer to a pmix_proc_t structure in which the client’s namespace and rank are to be returned. Passing NULL is allowed if the caller only wishes to initialize the PMIx system and does not require the identifier at this time.

18.2.2.4. DESCRIPTION

Initialize the PMIx client, returning the process identifier assigned to this client’s application in the provided pmix_proc_t struct. Passing a value of NULL for the proc parameter is allowed if the caller wishes solely to initialize the PMIx system and does not require return of the identifier at that time.

When called, the PMIx client will check for the required connection information of the local PMIx server and will establish the connection. If the information is not found, or the server connection fails, then an appropriate error constant will be returned.

If successful, the function will return PMIX_SUCCESS and will fill the provided structure (if non-NULL) with the server-assigned namespace and rank of the process within the application. In addition, all startup information provided by the resource manager is made available to the client process via subsequent calls to PMIx_Get(3).

The info array is used to pass user directives pertaining to the initialization and subsequent operations. These commonly describe the transport by which the client is to rendezvous with the local server, or announce the programming model and threading model being initialized so that the event notification system can coordinate among cooperating libraries within the same process (see DIRECTIVES).

18.2.2.4.1. Reference counting

The PMIx client library is reference counted, and so multiple calls to PMIx_Init are allowed. Thus, one way for an application process to obtain its namespace and rank is to simply call PMIx_Init with a non-NULL proc parameter. Each call to PMIx_Init must be balanced with a matching call to PMIx_Finalize(3) so that the connection to the local server is only torn down once every initializing caller has finalized.

Multiple calls to PMIx_Init must not include conflicting directives; an error is returned when directives that conflict with those of a prior call are encountered.

18.2.2.5. DIRECTIVES

The following attributes are relevant to this operation. Support for any given attribute is optional and depends on how the PMIx implementation was built and on the capabilities of the host environment.

18.2.2.5.1. Connection attributes

These attributes describe how the client is to rendezvous with the local PMIx server. They are consumed during connection establishment and are not typically retrievable via PMIx_Get(3).

PMIX_TCP_URI (char*) — the URI of the PMIx server to connect to, or a file name containing it in the form file:<name of file>.
PMIX_TCP_REPORT_URI (char*) — direct that the client’s TCP URI be reported, and indicate the method: '-' for stdout, '+' for stderr, or a filename.
PMIX_TCP_IF_INCLUDE (char*) — comma-delimited list of devices and/or CIDR notation to include when establishing the TCP connection.
PMIX_TCP_IF_EXCLUDE (char*) — comma-delimited list of devices and/or CIDR notation to exclude when establishing the TCP connection.
PMIX_TCP_IPV4_PORT (int) — the IPv4 port to be used.
PMIX_TCP_IPV6_PORT (int) — the IPv6 port to be used.
PMIX_TCP_DISABLE_IPV4 (bool) — set to true to disable the IPv4 family of addresses.
PMIX_TCP_DISABLE_IPV6 (bool) — set to true to disable the IPv6 family of addresses.
PMIX_USOCK_DISABLE (bool) — if the library supports Unix socket connections, disable their use.
PMIX_SOCKET_MODE (uint32_t) — set the mode of the rendezvous socket.
PMIX_SINGLE_LISTENER (bool) — if the library supports more than one method for clients to connect to servers, use only one of them.

18.2.2.5.2. Runtime attributes

PMIX_GDS_MODULE (char*) — select the generalized data store (GDS) component(s) the client is to use for storing and retrieving job-level and peer data. If not provided, the value of the PMIX_GDS_MODULE environment variable is honored, defaulting to the hash component.
PMIX_EVENT_BASE (void*) — pointer to an event_base to use in place of the internal progress thread. The event base must be compatible with the event library (e.g., libevent or libev) the PMIx implementation was built against.
PMIX_EXTERNAL_PROGRESS (bool) — the host will progress the PMIx library as needed via calls to PMIx_Progress (see PMIx_Progress(3)), rather than PMIx spawning its own internal progress thread.
PMIX_BIND_PROGRESS_THREAD (char*) — comma-delimited ranges of CPUs to which the internal PMIx progress thread is to be bound.
PMIX_BIND_REQUIRED (bool) — return an error if the internal PMIx progress thread cannot be bound as requested.
PMIX_EXTERNAL_AUX_EVENT_BASE (void*) — pointer to an event_base the library is to use for auxiliary functions (e.g., capturing signals) that would otherwise interfere with the host.

18.2.2.5.3. Programming-model attributes

When provided, the following attributes are used by the event notification system for inter-library coordination — for example, so that an MPI and an OpenMP runtime co-located in the same process can discover one another via a PMIX_MODEL_DECLARED event.

PMIX_PROGRAMMING_MODEL (char*) — programming model being initialized (e.g., "MPI" or "OpenMP").
PMIX_MODEL_LIBRARY_NAME (char*) — programming model implementation ID (e.g., "OpenMPI" or "MPICH").
PMIX_MODEL_LIBRARY_VERSION (char*) — programming model version string (e.g., "2.1.1").
PMIX_THREADING_MODEL (char*) — threading model used (e.g., "pthreads").
PMIX_MODEL_NUM_THREADS (uint64_t) — number of active threads being used by the model.
PMIX_MODEL_NUM_CPUS (uint64_t) — number of CPUs being used by the model.
PMIX_MODEL_CPU_TYPE (char*) — granularity: "hwthread", "core", etc.
PMIX_MODEL_AFFINITY_POLICY (char*) — thread affinity policy, e.g. "master", "close", or "spread".
PMIX_MODEL_PHASE_NAME (char*) — user-assigned name for a phase in the application’s execution (e.g., "cfd reduction").
PMIX_MODEL_PHASE_TYPE (char*) — type of phase being executed (e.g., "matrix multiply").

18.2.2.6. INITIALIZATION EVENTS

The following events are typically associated with calls to PMIx_Init and may be delivered to processes that have registered for them via PMIx_Register_event_handler (see PMIx_Register_event_handler(3)):

PMIX_MODEL_DECLARED — a programming model has been declared by a call to PMIx_Init that carried the programming-model attributes above.
PMIX_MODEL_RESOURCES — resource usage by a programming model has changed.
PMIX_OPENMP_PARALLEL_ENTERED — an OpenMP parallel code region has been entered.
PMIX_OPENMP_PARALLEL_EXITED — an OpenMP parallel code region has completed.

18.2.2.7. 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 library could not be initialized (for example, a required transport was explicitly disabled, or a tight race between concurrent PMIx_Init calls left the library in an unusable state).
PMIX_ERR_UNREACH — the local PMIx server could not be reached.
PMIX_ERR_NOT_SUPPORTED — a provided directive requested behavior the implementation does not support.

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

18.2.2.8. NOTES

PMIx_Init is intended for use by client processes — processes that were registered with a PMIx server before being started. Processes acting as tools (debuggers, profilers, workflow managers) should instead call PMIx_tool_init, and processes hosting a PMIx server should call PMIx_server_init.