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

[Julien Fischer]

On Sat, 16 Aug 2025 at 19:42, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
>
> 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?

Yes, .par is redundant for C# and Java.  (In fact,

> > (Neither supports parallel conjunctions.)
>
> I knew that, since only the LLDS backend has ever supported it.

It's not an entirely useless observation, Paul did some preliminary work on
supporting parallel conjunctions in the Java grade.

> > 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.

My understanding of the situation (which is not defence of it) is as follows:

C does not provide builtin support for threads.  One of the things that
the .par component does (for both MLDS-C and LLDS grades) is provide the
Mercury runtime and the generated code (through the runtime) access to
C-level thread
support (in practice, POSIX threads).  This is what the MLDS-C and
LLDS .par grades
have in common.  However, what is then done with that C-level thread
support differs
between the MLDS-C and LLDS backends.

For the MLDS-C grades, the C-level thread support enabled by the .par component
is used to enable support for concurrency (whether parallel or not).
In the model of
threading used by the MLDS-C .par grades, each Mercury thread is mapped onto a
C-level thread.  Those threads can execute in parallel, but do not
have to (e.g. if
you only have a single processor, then concurrency will be implemented
using time
slicing or somesuch.)  This is the *only* way to get user-level concurrency in
high-level C grades, thread.spawn/3 throws an exception in non .par hlc grades.

For the LLDS .par grades, the C-level thread support is used to create
a pool of C-level threads
each of which runs a Mercury engine.  Mercury threads are then
multiplexed onto those
engines in order to provide parallel concurrency.  One of the other
effects of the
.par grade component in LLDS grades is to enable support for parallel
conjunction
in the compiler and runtime.  Conjuncts from parallel conjunctions
will also be executed
on the engines running on the C-level threads.

(You can, in principle, get non-parallel concurrency in non .par LLDS grades,
but in practice that has never worked very well -- we might do better to get
thread.spawn/3 to also throw an exception in those grades.)

Finally, in both of the non-C grades support for target language-level
threads is part
of the language or standard library. The aspect of the .par grade that tells the
runtime to use an external thread library is unnecessary for them. For
both C# and Java,
Mercury threads are mapped onto target language-level threads.
Parallel conjunction is
not supported.

> > > +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?

Installing asm_fast.par.gc and trying to run some of the samples in
the concurrency
directory should be sufficient.  I'll install the asm_fast.par.gc
grade and give it a try.

Julien.