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.

---

Progress

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

Issue

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

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]

❗ This change is not yet ready to be integrated.
See the Progress checklist in the description for automated requirements.

[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.

[mlbridge]

Webrevs

• 00: Full (4bfc90a5)

[rose00]

This is looking good so far.

Obviously I agree with the definitions.

I like this useful parallelism:

The rest of the logical result is lost…
The rest of the output is padded with zero bits.

Good improvement to @throws documentation.

Very good test code.

Unslice should throw, clearly. Doing the same for all non-zero part numbers was an oversight.

I agree that it is very hard to balance the goals of completeness and "lightness" of presentation.

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 ;)

Until we have more reliable vector size changes (depending on synthetics) we are stuck with part numbers. We might as well explain them fully in the javadoc, which is the official API spec. We could add an essay or white paper off to the side somewhere which explains the part numbers at length. That could relocate some of the "heaviness" elsewhere.

In a possible future version of the API, we can delete the part numbers, and not the "why don’t you just" move of defaulting them to zero, which papers over the size-change problem without addressing it at the root. The future API version can add part-free API points which simply DTRT and produce a vector, possibly synthetic, of the right size. That will require JIT work to avoid having this simpler user model break performance expectations completely. More recent vector ISAs seem to be moving in this direction, of allowing flexible physical size changes in close harmony with logical size changes.

In the possible future, maybe that "part number essay" could carry more of the weight, since part numbers would not be in every user’s face the way they must be today.

[eme64]

@rose00 I just found that we accidentally had removed the unslice exception: #3804

I'll fix that then :)
There were no tests for it, so we it was easy to forget about the checks.