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

[Julien Fischer]

On Sat, 16 Aug 2025 at 23:54, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
> On Sat, 16 Aug 2025 23:29:47 +1000, Julien Fischer <jfischer at opturion.com> wrote:

...

> > 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.
>
> mt = multi-threading, I presume.

Correct.

> Yet you say later that concurrency (using multiple threads, even if on one CPU,
> will be supported in "Non .par LLDS grades". What is the reason for this support
> being a separate grade modifier for high level C, but a builtin-in capability
> in low level C?

In order to support concurrency, something has to have the capability to execute
Mercury threads.  In LLDS grades, that something is an engine.  Regardless of
whether we are in an LLDS .par grade or not, there will be at least one engine
present, so concurrency is always possible (albeit not in parallel in
the single engine case).
In non .par hlc grades there is nothing to execute the threads, since
C does not provide
that capability as part of the language. The pthreads library provides
the capability and
pthreads is only included in the .par grades.

(I suspect what happened here is that using the .par grade component with hlc
was just a convenient way of getting access to the required pthread
support, since
most of it already existed for use by the LLDS backend.)

> > 2. We restrict the .par component to be used with only the LLDS grades,
> > where it will retain its existing meaning for them.
>
> Agreed.
>
> > 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)
>
> Agreed about 1, 2 and 4. About 3, we should await the results of your test,
> and even then, I would need to see something equivalent to a design
> document that says how it is supposed to work, because without that,
> it cannot be maintained long term.

I tried (3) with asm_fast.gc on some of the concurrency examples earlier this
evening.  They seem to work.  That said, so far as I can recall, every
discussion
I've ever had about this capability is that it doesn't work well.  I would happy
to drop it and just not allow concurrency in non .par LLDS grades.

> > For (1) and (2), whether or not you get any parallelism depends on how many
> > processors you have available.
>
> Agreed.
>
> As an aside: I am sure you can still buy uniprocessors for e.g. embedded
> work, but can you actually by a PC today with a single-core CPU?
> I don't remember seeing one in ages.

I very much doubt it.  However, on Linux at least you can simulate the effect
of it by setting the processor affinity mask appropriately.

> Note also that agreeing on a scheme would be good,

Let me pose the first question as part of a proposed scheme: should
we continue to allow concurrency in non .par LLDS grades?  (Which is
a no from me.)

> but we would then
> need to agree on a road map for getting there, preferably with minimal
> disruption. Having ".par" be a synonym for "mt" in MLDS grades for a time
> will probably be involved.

Most probably.

Julien.