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

[Julien Fischer]

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.  (Neither supports parallel conjunctions.)

The main change that needs to be made to this diff is to say what happens for
the C# and Java grades and restrict the .par component to the C backends.

> Document the .par grade modifier.
>
> Make minor improvements elsewhere in the user guide.
>
> diff --git a/doc/mercury_user_guide.texi b/doc/mercury_user_guide.texi
> index d269c09cb..6a5a52be5 100644
> --- a/doc/mercury_user_guide.texi
> +++ b/doc/mercury_user_guide.texi
> @@ -1230,7 +1230,36 @@ This grade modifier is compatible only with base grades that target C.
>  @node Grade modifiers for parallelism
>  @subsection Grade modifiers for parallelism
>
> -ZZZ TODO
> +In the absence of the @code{.par} grade modifier,
> +the Mercury compiler generates executables
> +that do not support parallel execution in any form.

As mentioned, above, this is only true for the C backends.

> + at table @code
> + at item .par
> +Compiling programs in a grade that includes the @code{.par} grade modifier
> +generates executables that support parallel execution.
> +What form of parallel execution is supported depends on the backend.
> +
> + at itemize
> + at item
> +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.)

> +Programmers can ask the compiler to execute two goals in parallel
> +simply by replacing the comma (the sequential conjunction operator)
> +between them with an ampersand @samp{&}, the parallel conjunction operator.
> +The compiler will take care of the rest.
> +(Note that @samp{&} has this effect @emph{only} in LLDS @code{.par} grades;
> +in all other grades, the compiler silently converts all @samp{&}s into commas.)
> +
> +Note: due to a code generation bug,
> +at the moment LLDS parallelism does not work.
> + at end itemize
> + at end table
>
>  @c ----------------------------------------------------------------------------
>
> @@ -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).

Julien.