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

[Zoltan Somogyi]

On Mon, 18 Aug 2025 20:49:41 +1000, Julien Fischer <jfischer at opturion.com> wrote:

> On Mon, 18 Aug 2025 at 13:18, Peter Wang <novalazy at gmail.com> wrote:
> 
> > I'm not sure about having separate .par and .mt grade components. Is it
> > more confusing that you need to use "hlc.mt.gc" but "asm_fast.par.gc" to
> > get access to multi-threading, which is a practical way to exploit
> > parallelism?
> > On the other hand, parallel conjunction is just an
> > experiment feature; there are probably no real programs using it.

Given that at the moment, parallel conjunction does not work, I hope not.

> I think we should just bite the bullet and use separate grade
> components for concurrency
> and parallel conjunction across *all* of the C grades. 

Agreed.

> Yes, it's an
> extra grade component,
> but it simplifies the question of how do I get a C grade that supports
> concurrency?
> If we disable concurrency in the (as now) non .par LLDS grades, then
> having concurrency
> support is matter of either using a csharp or java grade, or using a C
> grade that has a ".mt"
> component.

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 :-(

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,

- document that we plan to rename the .par grade modifier to .mt
   after a transition period where both are valid,

- document that eventually, we intend to use the .par modifier
  for LLDS grades that support parallel conjunctions.

Implementing the second step would be easy, in fact it would be
easier than agreeing on and then writing the documentation :-(
Disabling thread ops in non-.mt C grades should not be hard either.

I don't have a position on the "should we support thread
operations in non-.mt LLDS, yeah or nay?" question, the above
assumes nay only because I sense that is what you guys have
converged on.

Does anyone have a differing proposal?

Zoltan.