On Fri, 13 Mar 2026 19:35:47 GMT, John R Rose <[email protected]> wrote:
>> TODO: `unslice` - throw exception or adjust documentation? >> - The documentation says we should throw if parts is not in `[0..1]` >> - The implementation does not throw, and just checks `part == 0`, i.e. >> separates zero and non-zero. >> For consistency with the part number elsewhere, we should probably throw in >> the implementation. >> >> -------------------------------------- >> >> 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 >> (https://github.com/openjdk/jdk/pull/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... > > 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. @rose00 I just found that we accidentally had removed the `unslice` exception: https://github.com/openjdk/jdk/pull/3804 I'll fix that then :) There were no tests for it, so we it was easy to forget about the checks. ------------- PR Comment: https://git.openjdk.org/jdk/pull/30113#issuecomment-4068281496
