8375631: VectorAPI part number: reformulate documentation and improve exception message

[eme64]

Found while working on JDK-8369699.

In general, the Vector API documentation is a bit vague around part numbers.
There was considerable confusion around expansion/contraction: are we talking about logical, physical or output expansion/contraction? Confusingly, in some places we called expansions things that go from more to fewer bits, and we called contractions that went from fewer to more bits.

And exception messages are not very helpful, for example they don't provide the legal range.

@rose00 took a first stab at improving things (#29306), and I eventually took over the project.

---

Principles:

• Expansion means fewer->more bits.
• Contraction means more->fewer bits.
• Be clear about input, logical result and output.
• We primarily use:
  • conversion lanewise expansion (logical)
  • conversion lanewise contraction (logical)
  • conversion lanewise in-place (logical)
  • reinterpret (logical)
  • select, for truncation (output)
  • insert, for padding (output)
  • in-place, logical fits output (output)

Please review this PR in this order:

• Changes in the "Expansions, contractions, and partial results" section of Vector.java. We must first agree on the definitions here, before we go and disagree elsewhere ;)
• Changes in affected methods convertShape, convert, and reinterpretShape.
• Internal changes in AbstractVector.java‎: adjust nomenclature and exception message.
• New test. I think it is necessary, I caught some mistakes I made. And when I wanted to add tests for unslice I realized that it does not throw for out of bounds part. So I think it is justified.

In general, I'm a bit worried that the documentation is a bit too long, and feels a bit heavy/overwhelming.
To a large degree, this is due to the complexity of part numbers.
We could drop some paragraphs and some repetition. Let me know what you think is too much.
More explanations may help make things clearer, but also risk being too much and overwhelming.
I'm open to cut things down more, and any other constructive suggestions ;)

---

While reading the documentation and testing for unslice, I found out that #3804 accidentally removed the bounds checks for part. But we did not notice, because there were no tests for it. I'm adding the bounds check back in and adding tests for it as well.

---

• I confirm that I make this contribution in accordance with the OpenJDK Interim AI Policy.

---

Progress

• Change must not contain extraneous whitespace
• Commit message must refer to an issue
• Change must be properly reviewed (2 reviews required, with at least 1 Reviewer, 1 Author)

Issue

• JDK-8375631: VectorAPI part number: reformulate documentation and improve exception message (Bug - P4)

Reviewers

• Paul Sandoz (@PaulSandoz - Reviewer) 🔄 Re-review required (review applies to c18508ec)

Contributors

• John R Rose <jrose@openjdk.org>

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/30113/head:pull/30113
$ git checkout pull/30113

Update a local copy of the PR:
$ git checkout pull/30113
$ git pull https://git.openjdk.org/jdk.git pull/30113/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 30113

View PR using the GUI difftool:
$ git pr show -t 30113

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/30113.diff

Using Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back epeter! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

@eme64 This change is no longer ready for integration - check the PR body for details.

[openjdk]

@eme64 The following label will be automatically applied to this pull request:

• core-libs

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

[eme64]

/contributor add @rose00

[openjdk]

@eme64
Contributor John R Rose <jrose@openjdk.org> successfully added.

[PaulSandoz]

We can either add documentation to package doc or to a separate HTML file in the same package. But for this review I realize I am likely asking too much, it would be better to consider that holistically.

I wonder if we can remove footnote-like text such as "(Some platforms do support a..."? and perhaps it is possible after the definitions to compress/remove most of the discussion before we focus on the various resizing operations, maybe provide a textual example for each, and then on to the table of the examples that amplifies with more examples?

[eme64]

@PaulSandoz Thanks for the online and offline comments!

I wonder if we can remove footnote-like text such as "(Some platforms do support a..."?

This was from @rose00 , so I have not yet dared to remove it. I think it also nicely explains the rationale behind part numbers. For example on NEON, we really currently can only use 64 and 128 bit vectors. That is a very narrow band, and makes casting less straight-forward: you need to think about inserting and selecting.

With synthetic vector shapes we can probably get around this. Even vector splitting could help: casting from 128 bit to 512 bit would then automatically split the 512 bit one into 4 vectors on NEON. At that point, we may need to re-write some of these sections.

@rose00 What is your opinion on this paragraph?

Quoting the whole thing for reference:

(Some platforms do support a rich variety of vector shapes, and can also natively express logical expansions and contractions of lanewise data, transparently adjusting vector shapes on the fly. But not all platforms have enough shapes to pull this off well. And in extreme cases a shape change is physically impossible, because the logical result would be just too large or too small to be matched by any available vector shape. So the Vector API only changes shapes in a method documented as shape-changing, and the user must supply the new shape explicitly.)

[eme64]

I was able to shave off 60 lines in fbb2ece. I slashed a lot of the "prose" part after the "definitions".

I compacted some details into the "definitions" (valid part ranges).

Instead, I added some examples. And reformulated some things into this section:

For conversions, one might be tempted to use in-place operations where the logical and physical expansion ratios are equal ML=MP, and no selection or insertion is required (part=0). Such code tends to be easier to read, since there is no changes to VLENGTH. However, some platforms only support one or two shapes (e.g. aarch64 NEON only supports 64 and 128 bit vectors), and so the code must be organized so that the physical expansion ratio does not change much. If the shapes cannot change, but lane sizes do change, then the code must perform selection or insertion (e.g. conversion byte[16]:128 -> long[2]:128 and long[2]:128 -> byte[16]:128). To achieve portable code, one has to consider consistently using shape-invariant conversions, so one never leaves the preferred shape.

Now we can probably delete this part, right?

(Some platforms do support a rich variety of vector shapes, and can also natively express logical expansions and contractions of lanewise data, transparently adjusting vector shapes on the fly. But not all platforms have enough shapes to pull this off well. And in extreme cases a shape change is physically impossible, because the logical result would be just too large or too small to be matched by any available vector shape. So the Vector API only changes shapes in a method documented as shape-changing, and the user must supply the new shape explicitly.)

@PaulSandoz @rose00 Does this look better now? What else would you like me to do now?

[eme64]

FYI: thanks to @rgiulietti for pushing me towards more compact formulations in offline conversations.

[eme64]

In 1a586e0 I now restructured the list of "resizing operations" a bit.

I'm now open to more reviews now :)

[PaulSandoz]

Suggested change

	* invariant lane size (lanewise in-place, {@code ML=1}),
	* length-invariant (lanewise in-place, {@code ML=1}),

?

[eme64]

Here I want to say that the lanes keep the same number of bits -> lanewise in-place. It is not about the number of lanes / length of the vector. What do you think?

[PaulSandoz]

Is that not implied by it also being shape-invariant? VLENGTH in and VLENGTH out, VSHAPE in and VSHAPE out. I would be inclined to just say "length-invariant ({@code ML=1"}), otherwise it might appear you are saying something different or new and that is not the case.

[eme64]

The implication can really go any way: if you have 2 corners of the triangle, you get the 3rd.
Question is if we first focus on the lane size or the number of lanes.

Generally, length-invariant does not imply ML=1.
I think length-invariant would go better with no selection/insertion here. I'll add it there.

[eme64]

@PaulSandoz Thanks for the many suggestions and the offline conversation. I think I addressed everything now.

[PaulSandoz]

Is that not implied by it also being shape-invariant? VLENGTH in and VLENGTH out, VSHAPE in and VSHAPE out. I would be inclined to just say "length-invariant ({@code ML=1"}), otherwise it might appear you are saying something different or new and that is not the case.

[eme64]

@PaulSandoz Ok, made another small adjustment according to what you suggested.

Ready for a second review :)

[eme64]

/template append

[openjdk]

@eme64 The pull request template has been appended to the pull request body

[openjdk]

@eme64 hotspot-compiler has been added to this pull request based on files touched in new commit(s).

[openjdk]

The total number of required reviews for this PR has been set to 2 based on the presence of this label: hotspot-compiler. This can be overridden with the /reviewers command.