On Tue, 31 Mar 2026 08:55:17 GMT, Emanuel Peter <[email protected]> wrote:
>> 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 ;) >> >> ----------------------- >> >> While reading the documentation and testing for `unslice`, I found out that >> https://github.com/openjdk/jdk/pull/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 ... > > Emanuel Peter has updated the pull request incrementally with one additional > commit since the last revision: > > COMPACT DOCS I was able to shave off 60 lines in https://github.com/openjdk/jdk/pull/30113/changes/fbb2ece6959d0eb9720a7286cb1c6a2182c81acf. 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? FYI: thanks to @rgiulietti for pushing me towards more compact formulations in offline conversations. ------------- PR Comment: https://git.openjdk.org/jdk/pull/30113#issuecomment-4161027891 PR Comment: https://git.openjdk.org/jdk/pull/30113#issuecomment-4161034599
