Clarify/fix description and usage of MPI_GROUP_NULL

[cniethammer]

Problem

MPI 4.0 Section 7.2.1 on page 314 defines the invalid group handle MPI_GROUP_NULL. It includes the following advice to users stating:

Advice to users. MPI_GROUP_EMPTY, which is a valid handle to an empty group,
should not be confused with MPI_GROUP_NULL, which in turn is an invalid handle.
The former may be used as an argument to group operations; the latter, which is
returned when a group is freed, is not a valid argument. (End of advice to users.)

The sessions model introduced the new function MPI_Group_from_session_pset that returns MPI_GROUP_NULL if a passed pset name is not known. Example 11.9 shows its usage. In this example the variable wgroup is initialized with the value MPI_GROUP_NULL and passed to MPI_Group_from_session_pset later unmodified.

So there are two issues for me with this:

• Example 11.9 uses an invalid group handle as argument, which contradicts the advice to users in 7.2.1.
• With MPI 4.0 MPI_GROUP_NULL can originate also from another function call, i.e., MPI_Group_from_session_pset, so it is not only returned when a group is freed as stated in the Advice to users.

Impact on Implementations

• Clarify usage of MPI_GROUP_NULL

Impact on Users

• Clarify usage of MPI_GROUP_NULL

References and Pull Requests

MPI 4.0 Section 7.2.1, Section 7.3.2, and Example 11.9

[hppritcha]

We discussed this issue in today's Sessions WG meeting. The example in 11.9 is passing a pointer to a variable of type MPI_Group not a pointer to MPI_GROUP_NULL so the WG thinks that example is correct.

The second point raises a good point and will be addressed by a pull request targeting the MPI 4.1 standard.

[cniethammer]

Thanks a lot for clarifying this in the WG and taking care of the second point.

[RolfRabenseifner]

The former may be used as an argument to group operations; the latter, which is returned when a group is freed, is not a valid argument. (End of advice to users.)

This sentence does not say "which is only returned when a group is freed".

Therefore, I would not see that the MPI standard is inconsistent, i.e., also other routines may return MPI_GROUP_NULL in a similar case, i.e., where there isn't a group that can be returned.
The currently proposed PR, that just removes the description of parts of the outcome of MPI_Group_from_session_pset would be a not backward compatible change with all of its consequences (deprecation, new routine, ...), which seems not to be worth in the case of a still consistent MPI-4.0. Maybe that a small comment that there are other usecases of MPI_GROUP_NULL, may resolve the problem more elegant.

[hppritcha]

I like @RolfRabenseifner 's suggestion.

[cniethammer]

Agree with @RolfRabenseifner.

For me adding an ",.e.g.," to the Advice to users seems sufficient to make the user aware of this

...; the latter, which is, e.g., returned when a group is freed, ...

[RolfRabenseifner]

And please be additionally aware of the use of MPI_REQUEST_NULL as output argument of MPI_WAIT & TEST and also as input argument of MPI_WAITALL & TESTALL, ...ANY, ...SOME.