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

[Zoltan Somogyi]

On Tue, 19 Aug 2025 16:15:58 +1000, Peter Wang <novalazy at gmail.com> wrote:
> On Mon, 18 Aug 2025 13:05:36 +0200 "Zoltan Somogyi" <zoltan.somogyi at runbox.com> wrote:
> > At the moment, it is not an *extra* grade component. It is a *rename*
> > of the .par grade component to .mt, given that parallel conjunction
> > does not work :-(
> 
> Did something break parallel conjunction?

Yes. It happened several years ago, but we don't know when or which commit,
because as far as I know, the nightly tests have never included asm_fast.gc.par :-(

> > I would be inclined to proceed as follows:
> > 
> > - document the current .par grade as providing multithreading in C,
> >   both LLDS and MLDS, with multithreading provided without .par
> >   in C# and Java,
> > 
> 
> Yes, this is what .par means.
> 
> > - document that we plan to rename the .par grade modifier to .mt
> >    after a transition period where both are valid,
> 
> If someone wants multiple (native) threads, it's pretty much because
> they want parallel execution.

Or they may want concurrency, which is not the same thing.

I have no dog in this fight. You and Julien should agree on something,
and when you do, tell me what it is, and I will document it.

> .mt is a bit more direct, but .par was
> fine as well. It's not worse than "asm_fast".

That's because for anyone you doesn't know the history, pretty much
no name is worse than asm_fast :-(

The point of the rename would be to free up the .par name for
parallel conjunctions. Of the two possible contenders for that name,
multithreading is the one that has the better chance for a good
alternate name.

> > - document that eventually, we intend to use the .par modifier
> >   for LLDS grades that support parallel conjunctions.
> 
> If a grade has the prerequisites to support parallel conjunction,
> and we've done the work to enable that support, I don't see why
> it needs to be gated behind another grade modifier.

Because enabling parallel conjunctions comes with overheads
that we don't want to pay for programs that contain no parallel
conjunctions.

And the reason why I originally wanted to document thread ops
as not being available in LLDS grades was precisely that I do not know
that we have done the necessary work to support multithreading
in those grades, even if engines support *some* aspects of it.
But there are many other parts of the system that could screw that up,
e.g. by using a static, non-thread-local buffer as temporary storage.
That would be a race condition bug, but like other such bugs, it
would have a chance to *look* like it works ok on workloads
where the race happens rarely.

> To bring the discussion away from the C grades for a moment, if someone
> decided to implement parallel conjunction for the Java or C# backends
> (which could be relatively easy compared to the C backends),
> would we insist that parallel conjunction only be enabled in separate
> java.par and csharp.par grades, when it could work just as well in the
> existing java or csharp grades? Why?

That would depend on whether they incurred overheads that were
needed only for parallel conjunctions.

The reason why Java/C# grades do not need .par grade modifiers now
is that we do not have a way to remove the overhead needed to support
threads from the .java/.cs files we generate. I have no idea whether
this will also be true for parallel conjunctions as well.

Zoltan.