Reference Implementation of the Process Management Interface Exascale (PMIx) standard
Downloads Privacy Policy Security Policy Publications Community ContributePMIx Groups
Support dynamic formation of process groups
[EXTENSION][CLIENT-API]
[IN PROGRESS]
Copyright (c) 2018 Intel, Inc. All rights reserved.
This document is subject to all provisions relating to code contributions to the PMIx community as defined in the community’s LICENSE file. Code Components extracted from this document must include the License text as described in that file.
PMIx Groups are defined as a collection of processes desiring a unified identifier for purposes such as passing events or participating in PMIx fence operations. Groups differ from processes that PMIx_Connect with each other in the following key areas:
Calls to PMIx_Group are first processed within the local PMIx server, which creates a tracker that associates the specified processes with the user-provided group identifier. Each process in the group is assigned a group rank based on their relative position in the array of processes provided in the call to Group_construct. In addition, each member of the group is provided with the job-level information of any other nspace represented in the group, and the contact information for all group members. Members of the group can subsequently utilize the provided group identifier in PMIx function calls to address the group’s members, using either PMIX_RANK_WILDCARD to refer to all of them or the group-level rank of specific members. The PMIx server will translate the specified processes into their RM-assigned identifiers prior to passing the request up to its host. Thus, the RM has no visibility into the group’s existence or membership.
Critical Note: User-provided group identifiers must be distinct from anything provided by the RM so as to avoid collisions between group identifiers and RM-assigned nspaces. This can best be accomplished through the use of an application-specific prefix – e.g., “myapp-foo”
Another way to think of it might be that members of PMIx Groups are “loosely” coupled as opposed to “tightly” connected when constructed via PMIx_Connect. The APIs are explained below.
Critical Note: The reliance on PMIx events in the PMIx Group concept dictates that processes utilizing these APIs must register for the corresponding events. Failure to do so will likely lead to operational failures. Users are recommended to utilize the PMIX_TIMEOUT directive (or retain an internal timer) on calls to PMIx Group APIs (especially the blocking form of those functions) as processes that have not registered for required events will never respond.
PMIX_EXPORT pmix_status_t PMIx_Group_construct(const char id[],
const pmix_proc_t procs[], size_t nprocs,
const pmix_info_t info[], size_t ninfo);
PMIX_EXPORT pmix_status_t PMIx_Group_construct_nb(const char id[],
const pmix_proc_t procs[], size_t nprocs,
const pmix_info_t info[], size_t ninfo,
pmix_op_cbfunc_t cbfunc, void *cbdata);
Construct a new group composed of the specified processes and identified with the provided group identifier. Both blocking and non-blocking versions are provided (the callback function for the non-blocking form will be called once all specified processes have responded). The group identifier is a user-defined, NULL-terminated character array of length less than or equal to PMIX_MAX_NSLEN. Only characters accepted by standard string comparison functions (e.g., strncmp) are supported. Processes may engage in multiple simultaneous group construct operations as desired so long as each is provided with a unique group ID. The info array can be used to pass user-level directives regarding timeout constraints and other options available from the PMIx server.
Some specific info keys relevant to this operation:
The construct leader (if PMIX_GROUP_LEADER is provided) or all participants will receive events (if registered for the PMIX_GROUP_INVITE_FAILED event) whenever a process fails or terminates prior to calling PMIx_Group_construct(nb) – the events will contain the identifier of the process that failed to join plus any other information that the resource manager provided. This provides an opportunity for the leader to react to the event – e.g., to invite an alternative member to the group or to decide to proceed with a smaller group. The decision to proceed with a smaller group is communicated to the PMIx library in the results array at the end of the event handler. This allows PMIx to properly adjust accounting for procedure completion. When construct is complete, the participating PMIx servers will be alerted to any change in participants and each group member will (if registered) receive a PMIXGROUP_MEMBERSHIP_UPDATE event updating the group membership.
Processes in a group under construction are not allowed to leave the group until group construction is complete. Upon completion of the construct procedure, each group member will have access to the job-level information of all nspaces represented in the group and the contact information for every group member.
Failure of the leader at any time will cause a PMIX_GROUP_LEADER_FAILED event to be delivered to all participants so they can optionally declare a new leader. A new leader is identified by providing the PMIX_GROUP_LEADER attribute in the results array in the return of the event handler. Only one process is allowed to return that attribute, declaring itself as the new leader. Results of the leader selection will be communicated to all participants via a PMIX_GROUP_LEADER_SELECTED event identifying the new leader. If no leader was selected, then the status code provided in the event handler will provide an error value so the participants can take appropriate action.
Any participant that returns PMIX_GROUP_CONSTRUCT_ABORT from the leader failed event handler will cause the construct process to abort. Those processes engaged in the blocking construct will return from the call with the PMIX_GROUP_CONSTRUCT_ABORT status. Non-blocking partipants will have their callback function executed with that status.
Implementation Note: The current PRI uses the host’s PMIx_Fence module function as the backend for this operation, thus avoiding definition of another host-to-server entry point. However, the signature of that function only involves passing of the proc array – thus, implementors may have used the proc array itself as the “signature” for identifying a given operation. If this was done, then multiple parallel calls to construct groups of different names but involving the same processes will conflict. Resolving the problem (either with a new entry point or attribute identifying the operation name) requires modifications to the PMIx server library’s host. This will be defined prior to adoption of the RFC.
PMIX_EXPORT pmix_status_t PMIx_Group_invite(const char grp[],
const pmix_proc_t procs[], size_t nprocs,
const pmix_info_t info[], size_t ninfo);
PMIX_EXPORT pmix_status_t PMIx_Group_invite_nb(const char grp[],
const pmix_proc_t procs[], size_t nprocs,
const pmix_info_t info[], size_t ninfo,
pmix_op_cbfunc_t cbfunc, void *cbdata)
Explicitly invite the specified processes to join a group. Each invited process will be notified of the invitation via the PMIX_GROUP_INVITED event. The processes being invited must register for the PMIX_GROUP_INVITED event in order to be notified of the invitation. The invitation event will include the identity of the inviting process plus the name of the group. When ready to respond, each invited process provides a response using the appropriate form of PMIx_Group_join. This will notify the inviting process that the invitation was either accepted (via the PMIX_GROUP_INVITE_ACCEPTED event) or declined (via the PMIX_GROUP_INVITE_DECLINED event). The PMIX_GROUP_INVITE_ACCEPTED event is captured by the PMIx client library of the inviting process – i.e., the application itself does not need to register for this event. The library will track the number of accepting processes and alert the inviting process (by returning from the blocking form of PMIx_Group_invite or calling the callback function of the non-blocking form) when group construction completes.
The inviting process should, however, register for the PMIX_GROUP_INVITE_DECLINED if the application allows invited processes to decline the invitation. This provides an opportunity for the application to either invite a replacement, declare “abort”, or choose to remove the declining process from the final group. The inviting process should also register to receive PMIX_GROUP_INVITE_FAILED events whenever a process fails or terminates prior to responding to the invitation. Actions taken by the inviting process in response to these events must be communicated at the end of the event handler by returning the corresponding result so that the PMIx library can adjust accordingly.
Upon accepting the invitation, all members of the new group will receive access to the job-level information of each other’s nspaces and the contact information of the other members.
Some specific info keys relevant to this operation:
The inviting process is automatically considered the leader of the asynchronous group construction procedure and will receive all failure or termination events for invited members prior to completion. The inviting process is required to provide a PMIX_GROUP_CONSTRUCT_COMPLETE event once the group has been fully assembled – this event will be distributed to all participants along with the final group membership.
Critical Note: Applications are not allowed to use the group in any operations until after receiving the PMIX_GROUP_CONSTRUCT_COMPLETE event signifying completion of group construction. This is required in order to ensure consistent knowledge of group membership across all participants.
Failure of the leader at any time will cause a PMIX_GROUP_LEADER_FAILED event to be delivered to all participants so they can optionally declare a new leader. A new leader is identified by providing the PMIX_GROUP_LEADER attribute in the results array in the return of the event handler. Only one process is allowed to return that attribute, declaring itself as the new leader. Results of the leader selection will be communicated to all participants via a PMIX_GROUP_LEADER_SELECTED event identifying the new leader. If no leader was selected, then the status code provided in the event handler will provide an error value so the participants can take appropriate action.
Any participant that returns PMIX_GROUP_CONSTRUCT_ABORT from the PMIX_GROUP_LEADER_FAILED event handler will cause all participants to receive an event notifying them of that status. Similarly, the leader may elect to abort the procedure by either returning PMIX_GROUP_CONSTRUCT_ABORT from the handler assigned to the PMIX_GROUP_INVITE_ACCEPTED or PMIX_GROUP_INVITE_DECLINED codes, or by generating an event for the abort code. Abort events will be sent to all invited participants.
/* define values associated with PMIx_Group_join
* to indicate accept and decline - this is
* done for readability of user code */
typedef enum {
PMIX_GROUP_DECLINE,
PMIX_GROUP_ACCEPT
} pmix_group_opt_t;
PMIX_EXPORT pmix_status_t PMIx_Group_join(const char grp[],
const pmix_proc_t *leader,
pmix_group_opt_t opt,
const pmix_info_t info[], size_t ninfo);
PMIX_EXPORT pmix_status_t PMIx_Group_join_nb(const char grp[],
const pmix_proc_t *leader,
pmix_group_opt_t opt,
const pmix_info_t info[], size_t ninfo,
pmix_op_cbfunc_t cbfunc, void *cbdata);
Respond to an invitation to join a group that is being asynchronously constructed. The process must have registered for the PMIX_GROUP_INVITED event in order to be notified of the invitation. When ready to respond, the process provides a response using the appropriate form of PMIx_Group_join.
Critical Note: Since the process is alerted to the invitation in a PMIx event handler, the process must not use the blocking form of this call unless it first “thread shifts” out of the handler and into its own thread context. Likewise, while it is safe to call the non-blocking form of the API from the event handler, the process must not block in the handler while waiting for the callback function to be called.
Calling this function causes the group “leader” to be notified that the process has either accepted or declined the request. The blocking form of the API will return once the group has been completely constructed or the group’s construction has failed (as described below) – likewise, the callback function of the non-blocking form will be executed upon the same conditions.
Some specific info keys relevant to this operation:
Failure of the leader at any time will cause a PMIX_GROUP_LEADER_FAILED event to be delivered to all participants so they can optionally declare a new leader. A new leader is identified by providing the PMIX_GROUP_LEADER attribute in the results array in the return of the event handler. Only one process is allowed to return that attribute, declaring itself as the new leader. Results of the leader selection will be communicated to all participants via a PMIX_GROUP_LEADER_SELECTED event identifying the new leader. If no leader was selected, then the status code provided in the event handler will provide an error value so the participants can take appropriate action.
Any participant that returns PMIX_GROUP_CONSTRUCT_ABORT from the leader failed event handler will cause all participants to receive an event notifying them of that status. Similarly, the leader may elect to abort the procedure by either returning PMIX_GROUP_CONSTRUCT_ABORT from the handler assigned to the PMIX_GROUP_INVITE_ACCEPTED or PMIX_GROUP_INVITE_DECLINED codes, or by generating an event for the abort code. Abort events will be sent to all invited participants.
PMIX_EXPORT pmix_status_t PMIx_Group_leave(const char grp[],
const pmix_info_t info[], size_t ninfo);
PMIX_EXPORT pmix_status_t PMIx_Group_leave_nb(const char grp[],
const pmix_info_t info[], size_t ninfo,
pmix_op_cbfunc_t cbfunc, void *cbdata);
Leave a PMIx Group. Calls to PMIx_Group_leave (or its non-blocking form) will cause a PMIX_GROUP_LEFT event to be generated notifying all members of the group of the caller’s departure. The function will return (or the non-blocking function will execute the specified callback function) once the event has been locally generated and is not indicative of remote receipt. All PMIx-based collectives such as PMIx_Fence in action across the group will automatically be adjusted if the collective was called with the PMIX_GROUP_FT_COLLECTIVE attribute (default is false) – otherwise, the standard error return behavior for that collective will be executed.
Critical Note: The PMIx_Group_leave API is intended solely for asynchronous departures of individual processes from a group as it is not a scalable operation – i.e., when a process determines it should no longer be a part of a defined group, but the remainder of the group retains a valid reason to continue in existence. Developers are advised to use PMIx_Group_destruct (or its non-blocking form) for all other scenarios as it represents a more scalable operation.
PMIX_EXPORT pmix_status_t PMIx_Group_destruct(const char grp[],
const pmix_info_t info[], size_t ninfo);
PMIX_EXPORT pmix_status_t PMIx_Group_destruct_nb(const char grp[],
const pmix_info_t info[], size_t ninfo,
pmix_op_cbfunc_t cbfunc, void *cbdata);
Destruct a group identified by the provided group identifier. Both blocking and non-blocking versions are provided (the callback function for the non-blocking form will be called once all members of the group have called “destruct”). Processes may engage in multiple simultaneous group destruct operations as desired so long as each involves a unique group ID. The info array can be used to pass user-level directives regarding timeout constraints and other options available from the PMIx server.
Some specific info keys relevant to this operation:
The destruct API will return an error if any group process fails or terminates prior to calling PMIx_Group_destruct or its non-blocking version unless the PMIX_GROUP_NOTIFY_TERMINATION attribute was provided (with a value of true) at time of group construction. If notification was requested, then an event will be delivered for each process that fails to call destruct and the destruct tracker updated to account for the lack of participation. The PMIx_Group_destruct operation will subsequently return PMIX_SUCCESS when the remaining processes have all called destruct – i.e., the event will serve in place of return of an error.
Implementation Note: The current PRI uses the host’s PMIx_Fence module function as the backend for this operation, thus avoiding definition of another host-to-server entry point. However, the signature of that function only involves passing of the proc array – thus, implementors may have used the proc array itself as the “signature” for identifying a given operation. If this was done, then multiple parallel calls to destruct groups of different names but involving the same processes will conflict. Resolving the problem (either with a new entry point or attribute identifying the operation name) requires modifications to the PMIx server library’s host.
The prototype implementation of the PMIx Group support is provided in the topic/group branch of the PMIx project repository.
Ralph H. Castain
Intel, Inc.
Github: rhc54