progress_required wording is ambiguous

The current semantics for bool upcxx::progress_required(persona_scope &ps); includes wording of the form:

The qualifier nearly here has two different meanings depending on the relevant persona:
For non-master personas: A return value of true means this persona requires further internal progress...
For the master persona: A return value of true means...

However, the function semantics need to define a single return value that corresponds to the set of personas selected by ps, which in general could include a mix of master and non-master personas. I suspect this is ambiguous in the current description, because it's unclear how the guarantees from each case are combined in a call that includes more than one persona. For example, in call that selects two non-master personas and returns true, the wording implies that BOTH of those personas need additional internal progress, when in reality the implementation may have just been forced to conflate the result to conform to the single return value.

I think the fix is to change the labels on the cases to something more like:

If ps includes the master persona...
// define what return true and false value means for the set of input personas
If ps does not include the master persona...
// define what return true and false value means for the set of input personas

Here the true cases would use wording like "one or more of the input personas requires internal progress", and the false case for no master personas wording like "none of the input personas requires internal progress"

This approach seems more straightforward and easier to interpret/use/implement correctly.

Comments (4)