[m-rev.] for post-commit review: document .par grades

[Zoltan Somogyi]

On Sat, 16 Aug 2025 14:41:51 +1000, Julien Fischer <jfischer at opturion.com> wrote:

> On Sat, 16 Aug 2025 at 00:07, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
> >
> > For review by anyone whose uses .par grades.
> >
> > I specifically want to know: is my description MLDS .par grades correct?
> 
> No, it isn't.
> 
> > Are java.par and csharp.par actually different from
> > just java and csharp grades, and if so, how?
> 
> .par has no meaning for the java and csharp grades. Those base grades support
> parallel multithreading directly.

The compiler accepts java.par as well as java. If there is no difference between them,
then the compiler should reject the .par grade modifier as redundant in this case,
and for csharp as well. Do you agree?

> (Neither supports parallel conjunctions.)

I knew that, since only the LLDS backend has ever supported it.

> The main change that needs to be made to this diff is to say what happens for
> the C# and Java grades

The reason why I asked for info about the MLDS part of .par grades twice now
is that I *don't know* what happens, and I said so explicitly. Telling me
"that's not right" does not help; what would help is telling me what *is* right.

> > +With the MLDS backend, @code{.par} grades support user-managed parallelism,
> > +using whatever thread support is provided by the target language.
> > +Programmers can use the operations
> > +of the @code{thread} module of the Mercury standard library
> > +to spawn new threads, and to collect their results once they are done.
> > + at item
> > +With the LLDS backend, @code{.par} grades support compiler-managed parallelism.
> 
> User-managed parallelism is also supported by the LLDS backend.
> (At least, it is *meant* to be supported; I don't know whether it
> currently works.)

I don't know either, and since I have never used user-managed parallelism
in any form, I don't have a convenient way to find out either. I believe you guys do.
Am I wrong about that?

> > @@ -1271,9 +1300,16 @@ at the cost of a much more complicated execution model.
> >  This solution gets its name, @dfn{minimal model tabling},
> >  from the fact that it is intended to return,
> >  for each query, all the answers that match that query
> > -in the @dfn{minimal model} of the program.
> > - at c ZZZ I can't find a good wikipedia reference
> > -It consists of
> > +in a specific @dfn{minimal model} of the program,
> > +named the @dfn{perfect model}.
> > +(We call it ``minimal model tabling'' instead of ``perfect model tabling''
> > +because the former is the standard terminology for this kind of tabling
> > +in the logic programming literature.)
> > + at c ZZZ Wikipedia has no reference for perfect model semantics.
> > + at c We could point to Przymusinski's paper titled
> > + at c "On the declarative and procedural semantics of logic programs".
> 
> This discussion of model semantics overlaps with the reference manual (in
> the section on tabling).

I will add a cross reference.

Thanks for the review.

Zoltan.