[m-rev.] for review: document require_tail_recursion pragmas

[Julien Fischer]

On Sun, 21 Jun 2026 at 18:58, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
>
> On Wed, 10 Jun 2026 21:23:20 +1000, Julien Fischer <jfischer at opturion.com> wrote:
> > Trailing inhibits tail recursion in certain (fortunately rare) circumstances.
> > Specifically, when we add trail ops. to a model_det or model_semi
> > disjunction, we add some trail ops. after each disjunct goal in order to
> > handle the commit.
> >
> > The attached test case is a contrived example of this.  In non-trailing
> >  MLDS grades it is tail-recursive, but in trailing MLDS grades it is not
> > tail recursive (and we get a warning because of the pragma).
>
> With the current compiler, we do not get a warning for this code,
> unless the pragma is modified to add the "in_all_grades" option.
> I expect that the warning you got was from an installed compiler
> that did not include the diff I committed that added trailing to
> the list of grade components that make a grade a non-tail-rec grade.

It was almost certainly a compiler that did not include that diff.

> > I'm not sure what the situation with the LLDS backend is. (It adds
> > trail ops. directly in the code generator, as opposed to using
> > add_trail_ops.).
>
> In that case, you won't get a warning even if add the in_all_grades option,
> precisely because, as you say, the trail op is not in the HLDS, but is
> added later.

Trailing could be implemented as an HLDS->HLDS transformation for
the LLDS backend as well, although that would probably entail teaching
some of the other LLDS-specific HLDS->HLDS transformations (e.g.
deep profiling) about tail ops. In short, it would be a significant amount
of work, for not much gain.

> This is such a niche difference that I don't think it would serve any useful
> purpose to refer to it in the manual; I think any reference would be
> much more likely to confuse than enlighten.

For me, the problem is that the updated reference manual section
now suggests that tail recursion with trailing is *not* supported. That
is far from the truth. With the exception of commits, the trailing
transformation otherwise preserves tail recursion.

Given that trailing grades are actually used in production, I don't
think this is the impression we should give.

> I am committing the attached updated diff, in which I addressed all your
> previously raised points. There is no interdiff, because some parts of the diff
> make sense only in view of context that the interdiff would omit.
>
> I will address any issues raise post-commit. When we agree, I intend to add a note
> announcing these pragmas to NEWS.md.

You can go ahead and announce the pragmas in the NEWS file. There's not any
point in waiting.

Julien.