[docs] loop pragmas

[SjoerdMeijer]

Summary

Following our discussion on the cfe dev list
(http://lists.llvm.org/pipermail/cfe-dev/2019-August/063054.html), I have added
a paragraph that is explicit about transformation options implying
the corresponding transformation.

[Meinersbur]

Since this is user documentation, we should only add it here once it is true.

docs/LanguageExtensions.rst

3068–3069 ↗

(On Diff #215031)

vectorize_width also "controls" a transformation. Is it that in our interpretation, vectorize(enable) overrides the profitability heuristic by taking out the "do not apply at all" option without setting any other option?

[SjoerdMeijer]

Since this is user documentation, we should only add it here once it is true.

Yep, good point, I also wanted to capture our discussions on the list. But yes, let's hold this back until we're ready with the pragmas.

docs/LanguageExtensions.rst

3068–3069 ↗

(On Diff #215031)

I think I need to think a little bit more about this:

Is it that in our interpretation, vectorize(enable) overrides the profitability heuristic by taking out the "do not apply at all" option without setting any other option?

but I would answer this with "yes". But just checking, what exactly do you mean with "do not apply at all option"?

[Meinersbur]

docs/LanguageExtensions.rst

3068–3069 ↗

(On Diff #215031)

I unfortunately mixed two meanings of "option" here:

1. option as in optimization setting
2. option as in candidate to choose from.

Let's take a look on the loop vectorizer. The profitability heuristic's job is too choose the "best" candidate out of the following list (independently of how LoopVectorize's heuristic is actually implemented; these might be decision made independently of each other, but as the user still sees one of the following outcomes):

0) no vectorization (the "do not apply at all" option/candidate)
1a) vec width=2 with epilogue
1b) vec width=2 without epilogue
2a) vec width=4 with epilogue
2b) vec width=4 without epilogue
3a) vec width=8 with epilogue
3b) vec width=8 without epilogue
...

vectorize(enable) with remove 0) as a candidate. vecorize(disable) will remove all expect 0) as a candidate.

The option/settings are vectorize_width and vectorize_predicate (and interleave_count). For instance vectorize_width(4) would remove 1) and 3)+ from the candidate list. vectorize_predicate(enable) takes any a) candidate from the list. What we were discussing was that these settings would remove 0) from the candidate list as well.

[SjoerdMeijer]

Many thanks for your clarification!

What we were discussing was that these settings would remove 0) from the candidate list as well.

Yep, that's crystal clear now.
And my expectation would indeed be that this would be the case.

[SjoerdMeijer]

I have committed all my pragma patches, so now back to the last bit, this doc update.
This doc change should now reflect our implementation. Are we happy for this to go in?

[hsaito]

docs/LanguageExtensions.rst

3069 ↗

(On Diff #215031)

and there loop hints ==> and there are loop hints

[SjoerdMeijer]

Thanks! Typo fixed.

[hsaito]

LGTM. Please wait for a few days in case others have more comments.

[SjoerdMeijer]

Sure, will do, thanks again for taking a look.

clang/docs/LanguageExtensions.rst

 ======================================
 
 The ``#pragma clang loop`` directive is used to specify hints for optimizing the
 subsequent for, while, do-while, or c++11 range-based for loop. The directive
 provides options for vectorization, interleaving, predication, unrolling and
 distribution. Loop hints can be specified before any loop and will be ignored if
 the optimization is not safe to apply.
 
+There are loop hints that control transformations (e.g. vectorization, loop
+unrolling) and there are loop hints that set transformation options (e.g.
+``vectorize_width``, ``unroll_count``).  Pragmas setting transformation options
+imply the transformation is enabled, as if it was enabled via the corresponding
+transformation pragma (e.g. ``vectorize(enable)``). If the transformation is
+disabled  (e.g. ``vectorize(disable)``), that takes precedence over
+transformations option pragmas implying that transformation.
+
 Vectorization, Interleaving, and Predication
 --------------------------------------------
 
 A vectorized loop performs multiple iterations of the original loop
 in parallel using vector instructions. The instruction set of the target
 processor determines which vector instructions are available and their vector
 widths. This restricts the types of loops that can be vectorized. The vectorizer
 automatically determines if the loop is safe and profitable to vectorize. A