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

[Julien Fischer]

On Sat, 16 Aug 2025 at 22:49, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
>
>
> On Sat, 16 Aug 2025 21:50:05 +1000, Julien Fischer <jfischer at opturion.com> wrote:
>
> > 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,
>
> Was something supposed to follow this?

No.

> > 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.
>
> Thanks for that info; it helps a lot.

Thinking about all of the above a bit more, or more specifically,
thinking about how
earth we explain it all, let me propose the following:

1. We introduce a new grade component ".mt", whose sole function is
enable support for concurrency in high-level C grades.  The new component
does not apply to the C#, Java or LLDS grades.

2. We restrict the .par component to be used with only the LLDS grades,
where it will retain its existing meaning for them.

Under this scheme, concurrency will be supported in

1. The Java and C# grades.
2. The hlc.mt grades.
3. Non .par LLDS grades (not in parallel)
4. .par LLDS grades (in parallel)

For (1) and (2), whether or not you get any parallelism depends on how many
processors you have available.

Julien.