19.2.266. PMIx_server_define_process_set

PMIx_server_define_process_set — Define a PMIx process set.

19.2.266.1. SYNOPSIS

#include <pmix_server.h>

pmix_status_t PMIx_server_define_process_set(const pmix_proc_t *members,
                                             size_t nmembers,
                                             const char *pset_name);

19.2.266.1.1. Python Syntax

from pmix import *

foo = PMIxServer()
# ... after a successful foo.init() ...
# members is a list of proc dicts, each {'nspace': ns, 'rank': r}
members = [{'nspace': 'myjob', 'rank': 0},
           {'nspace': 'myjob', 'rank': 1}]
rc = foo.define_process_set(members, 'myset')

19.2.266.2. INPUT PARAMETERS

members: Pointer to an array of pmix_proc_t(5) structures containing the identifiers of the processes that are members of the process set.
nmembers: Number of elements in the members array.
pset_name: NULL-terminated string name of the process set being defined.

19.2.266.3. DESCRIPTION

Provide a function by which the host environment can create a named process set — a user-defined grouping of processes identified by a string name and an associated membership list. Unlike a PMIx group (see PMIx_Group_construct), a process set is purely a label applied by the host environment; it establishes no collective context and requires no participation by the member processes.

When called, the PMIx server library records the process set (name and membership) so that it can later respond to client queries such as PMIX_QUERY_NUM_PSETS and PMIX_QUERY_PSET_NAMES, and it alerts all local clients to the new process set by generating a PMIX_PROCESS_SET_DEFINE event. The event carries the PMIX_PSET_NAME attribute (the set name) and the PMIX_PSET_MEMBERS attribute (a pmix_data_array_t of the member pmix_proc_t identifiers).

PMIx_server_define_process_set is a blocking call. Internally it thread-shifts the request onto the PMIx progress thread, records the set, emits the local notification, and returns once that processing is complete. The input members array need only remain valid for the duration of the call; the library retains its own copy of the membership.

19.2.266.4. RETURN VALUE

Returns one of the following:

PMIX_SUCCESS — the process set was defined and the local notification was issued.
PMIX_ERR_INIT — the PMIx server library has not been initialized.
PMIX_ERR_NOT_AVAILABLE — the library’s progress engine has been stopped, so the request cannot be serviced.

PMIx error constants are defined in pmix_common.h.

19.2.266.5. NOTES

This API is restricted to the server role and must be called only after a successful PMIx_server_init(3).

The host environment is responsible for ensuring consistent knowledge of process set membership across all involved PMIx servers, and for ensuring that process set names do not conflict with system-assigned namespaces within the scope of the set. The PMIx library only records and advertises the definition on the local server; it does not propagate it to peer servers.

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