CC @golang/compiler.

I think in general Go will not have many compiler directives/pragmas for optimization hints. go:noinline is not an optimization hint. It is mostly used for correctness, (e.g. some runtime functions must not be inlined), and for testing (e.g. to ensure certain code-generation behavior). It tells the compiler not to do an optimization, and PGO must respect it. More generally, if in the future we introduce pragmas to instruct the compiler not to do certain optimizations, PGO should respect them as well and not apply the optimizations.

I'm not sure what to document specifically. Maybe we could add that with go:noinline, it will not be inlined even with PGO. But that doesn't seem really necessary -- go:noinline is simply not inline in all situations, including PGO.

If later we introduce a compiler directive that has interesting interactions with PGO, we can document that.

I understand it, but from the current Go documentation:

The //go:noinline directive must be followed by a function declaration. It specifies that calls to the function should not be inlined, overriding the compiler's usual optimization rules. This is typically only needed for special runtime functions or when debugging the compiler.

According to this, "function should not be inlined" I see "should not". I cannot read it right now as "a function with go:noinline directive is NEVER inlined". That's why I am asking the question. From my current reading, go:noinline directive tunes somehow inlining rules. So if the current behavior is NEVER inline - would be great if the wording would be somehow changed to make it more clear for the end-users.

I agree the current wording is fine. I don't want us to overcommit on //go: directive support.

cmd/go documents and supports more directives that are user targeted. The cmd/compile directives are for low-level details that most users shouldn't need to use or worry about.

If the current wording is fine, then I am kindly asking to add a note somewhere that the PGO optimization does not affect the inlining decisions for the functions with go:noinline attribute :) I think adding a small note to the go:noinline description about that would be fine.

But why? Who does that help?

But why? Who does that help?

This information is important for people, who optimize their programs. As you know, inlining decisions could be critical in some cases. E.g. performing extra inlining in the "wrong" place could affect the code size. Code size characteristics could be critical in certain situations. If the compiler has go:noinline directive that means there are cases where it's important to the people. Otherwise, my question is - why did you implement it in the compiler? :) If it's important for the users, they want to know, in which cases the go:noinline behavior can be changed. Applying PGO - one of the cases (which is not unique for the Go compiler - see the corresponding LLVM issue).

If you are strictly against adding such implementation detail to the documentation - okay, it's of course up to the development team. Hopefully, if someone is interested a lot about the question - they will be able to dig into the compiler and search over the GitHub issue. This way has worse UX but reduces the documentation maintenance cost.

I don't what to get to too much about wording (and I'm not an expert on it). But I think at least in this case, "should not" means never. It is not a hint, but a requirement.

Regarding meanings of words like "should", "may" and others - to eliminate different readings of the same words I like to use RFC 2119 (https://datatracker.ietf.org/doc/html/rfc2119). Maybe I am a bit pedantic in this area since I spent several years of my life with the C++ standardization process... :)

Of course, if it's the well-known fact in this area of Go that "should" has other meaning than a recommendation, the current wording is fine.

If the compiler does something it "should not" do, I'd think that is a very bad thing and only creates confusions.
That said, personally I would not oppose to changing "should not" to "must not".

In compiler/runtime triage, we don't think we're going to do anything here. However, if you'd like to send a CL to alter the wording, that's fine with us. Thanks.