On Fri, 6 Mar 2026 10:47:02 GMT, Emanuel Peter <[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 cut things down more, and any other constructive suggestions ;) 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. ------------- PR Comment: https://git.openjdk.org/jdk/pull/30113#issuecomment-4057512563
