18.2.265. PMIx_server_define_process_set

PMIx_server_define_process_set — Define a PMIx process set.

18.2.265.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);

18.2.265.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')

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

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

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

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